NFTokenAcceptOffer
Non-fungible token functionality is part of the NonFungibleTokensV1 amendment to the XRP Ledger protocol. You can use these functions on the NFT-Devnet now, but they are not yet available on the production Mainnet.
The NFTokenAcceptOffer
transaction is used to accept offers to buy
or sell
an NFToken
. It can either:
- Allow one offer to be accepted. This is called direct mode.
- Allow two distinct offers, one offering to buy a given
NFToken
and the other offering to sell the sameNFToken
, to be accepted in an atomic fashion. This is called brokered mode.
Brokered vs. Direct Mode
The mode in which the transaction operates depends on the presence of the NFTokenSellOffer
and NFTokenBuyOffer
fields of the transaction:
NFTokenSellOffer |
NFTokenBuyOffer |
Mode |
---|---|---|
✔️ | ✔️ | Brokered |
✔️ | X | Direct |
X | ✔️ | Direct |
If neither of those fields is specified, the transaction is malformed and produces a tem
class error.
The semantics of brokered mode are slightly different than one in direct mode: The account executing the transaction functions as a broker, bringing the two offers together and causing them to be matched, but does not acquire ownership of the involved NFT, which will, if the transaction is successful, be transferred directly from the seller to the buyer.
Execution Details
Direct Mode
In direct mode, NFTokenAcceptOffer
transaction fails if:
- The
NFTokenOffer
against whichNFTokenAcceptOffer
transaction is placed is an offer tobuy
theNFToken
and the account executing theNFTokenAcceptOffer
is not, at the time of execution, the current owner of the correspondingNFToken
. - The
NFTokenOffer
against whichNFTokenAcceptOffer
transaction is placed is an offer tosell
theNFToken
and was placed by an account which is not, at the time of execution, the current owner of theNFToken
- The
NFTokenOffer
against whichNFTokenAcceptOffer
transaction is placed is an offer tosell
theNFToken
and was placed by an account which is not, at the time of execution, theAccount
in the recipient field of theNFTokenOffer
, if there exist one. - The
NFTokenOffer
against whichNFTokenAcceptOffer
transaction is placed specifies anexpiration
time and the close time field of the parent of the ledger in which the transaction would be included has already passed. - The
NFTokenOffer
against whichNFTokenAcceptOffer
transaction is placed to buy or sell theNFToken
is owned by the account executing theNFTokenAcceptOffer
.
A side-effect of such failures is the removal of the NFTokenOffer
object and the refund of the incremental reserve as if the offer had been cancelled. This necessitates the use of an appropriate tec
class error.
If the transaction is executed successfully then:
- The relevant
NFTtoken
changes ownership, meaning that the token is removed from theNFTokenPage
of the existingowner
and added to theNFTokenPage
of the newowner
. - Funds are transferred from the buyer to the seller, as specified in the
NFTokenOffer
. If the correspondingNFToken
offer specifies aTransferRate
, then theissuer
receives the specified percentage, with the balance going to the seller of theNFToken
.
Brokered Mode
In brokered mode, the NFTokenAcceptOffer
transaction fails if:
- The
buy
NFTokenOffer
against which theNFTokenAcceptOffer
transaction is placed is owned by the account executing the transaction. - The
sell
NFTokenOffer
against which theNFTokenAcceptOffer
transaction is placed is owned by the account executing the transaction. - The account that placed the offer to sell the
NFToken
is not, at the time of execution, the current owner of the correspondingNFToken
. - Either offer (
buy
orsell
) specifies anexpiration
time and the close time field of the parent of the ledger in which the transaction would be included has already passed.
Fields
NFTokenAcceptOffer Fields
In addition to the common fields, a NFTokenAcceptOffer transaction uses the following fields:
Field | JSON Type | Internal Type | Description |
---|---|---|---|
NFTokenSellOffer |
String | Hash256 | (Optional) Identifies the NFTokenOffer that offers to sell the NFToken . |
NFTokenBuyOffer |
String | Hash256 | (Optional) Identifies the NFTokenOffer that offers to buy the NFToken . |
NFTokenBrokerFee |
Currency Amount | Amount | (Optional) This field is only valid in brokered mode, and specifies the amount that the broker keeps as part of their fee for bringing the two offers together; the remaining amount is sent to the seller of the NFToken being bought. If specified, the fee must be such that, prior to accounting for the transfer fee charged by the issuer, the amount that the seller would receive is at least as much as the amount indicated in the sell offer. |
In direct mode, you must specify either the NFTokenSellOffer
or the NFTokenBuyOffer
field. In brokered mode, you must specify both fields.
This functionality is intended to allow the owner of an NFToken
to offer their token for sale to a third party broker, who may then attempt to sell the NFToken
on for a larger amount, without the broker having to own the NFToken
or custody funds.
If both offers are for the same asset, it is possible that the order in which funds are transferred might cause a transaction that would succeed to fail due to an apparent lack of funds. To ensure deterministic transaction execution and maximize the chances of successful execution, the account attempting to buy the NFToken
is debited first. Funds due to the broker are credited before crediting the seller.
In brokered mode, the offers referenced by NFTokenBuyOffer
and NFTokenSellOffer
must both specify the same NFTokenID
; that is, both must be for the same NFToken
.
Error Cases
In addition to errors that can occur for all transactions, NFTokenAcceptOffer transactions can result in the following transaction result codes:
Error Code | Description |
---|---|
temDISABLED |
The NonFungibleTokensV1 amendment is not enabled. |
temMALFORMED |
The transaction was not validly formatted. For example, it specified neither NFTokenSellOffer nor NFTokenBuyOffer , or it specified a negative NFTokenBrokerFee . |
tecCANT_ACCEPT_OWN_NFTOKEN_OFFER |
The buyer and seller are the same account. |
tecEXPIRED |
An offer specified in the transaction has already expired. |
tecINSUFFICIENT_FUNDS |
The buyer does not have the full amount they are offering. If the buy amount is specified in XRP, this could be because of the reserve requirement. If the buy amount is a token, it could be because the token is frozen. |
tecINSUFFICIENT_PAYMENT |
In brokered mode, the buy amount offered is not high enough to pay the BrokerFee and the sell cost of the NFToken . |
tecOBJECT_NOT_FOUND |
One of the offers specified in the transaction does not exist in the ledger. |
tecNFTOKEN_BUY_SELL_MISMATCH |
In brokered mode, the two offers are not a valid match. For example, the seller is asking more than the buyer is offering, the buy and sell offer are denominated in different assets, or the seller specified a destination that is not the buyer or the broker. |
tecNFTOKEN_OFFER_TYPE_MISMATCH |
The object identified by the NFTokenBuyOffer is not actually a buy offer, or the object identified by the NFTokenSellOffer is not actually a sell offer. |
tecNO_PERMISSION |
The seller does not own the NFToken being sold; or the matching offer specifies a different Destination account than the account accepting the offer. |