Trades

Trading allows players to buy and sell in-game items. The ability to trade items can add depth and complexity to the game, making it more engaging for players by adding an additional layer of strategy and decision-making. Trading helps manage in-game economies and trading systems to ensure fairness and security.

Creating a Trade

A trade involves an exchange of items or in-game resources between two players. To initiate a trade, a player (the offeror) accesses their inventory to select the items they want to trade (the offering). The player also requests certain items in return for their offering.

Private Trades

It is possible to create a private trade between two specific players by specifying an offereeId to enter the trade.

In the following example, Player 1 has an NFT in their item balance that they would like to trade Player 2 in exchange for some in-game tokens.

The first step is to call the Create Trade endpoint to initiate the trade.

{
  "offering": [
    {
      "quantity": "1",
      "itemId": "{{NFTItemId}}"
    }
  ],
  "requesting": [
    {
      "quantity": "1",
      "itemId": "{{FTItemId}}"
    }
  ],
  "offerorId": "{{player1Id}}",
  "offereeId": "{{player2Id}}"
}

{
    "trade": {
        "offereeId": "{{player2Id}}",
        "offerorId": "{{player1Id}}",
        "status": "offered",
        "id": "40bdf612-2546-41aa-a8cd-4e9b2eece9b1",
        "lines": [
            {
                "tradeId": "40bdf612-2546-41aa-a8cd-4e9b2eece9b1",
                "playerId": "{{player1Id}}",
                "itemId": "{{NFTItemId}}",
                "quantity": "1",
                "gameId": 1540,
                "id": "f40e15c7-1711-4cd9-82bd-25b250634f44"
            },
            {
                "tradeId": "40bdf612-2546-41aa-a8cd-4e9b2eece9b1",
                "playerId": "{{player2Id}}",
                "itemId": "{{FTItemId}}",
                "quantity": "1",
                "gameId": 1540,
                "id": "57e0773c-7f78-4a31-9189-339d0421832d"
            }
        ]
    },
    "itemBalances": [
        {
            "itemId": "{{NFTItemId}}",
            "playerId": "{{player1Id}}",
            "amount": "0"
        }
    ]
}

Once a trade is created, you will see an array of line items for each item being offered and requested. Notice that the amount of the offered item(s) is reduced, which means that it is removed from the offeror's available inventory.

Executing a Trade

It is good practice to have both players confirm that they are satisfied with the trade offer. This typically involves a final review of the items being traded.

If the offeree accepts the trade offer, the next step is to call the Accept Trade endpoint to execute the trade.

{
  "offereeId": "{{player2Id}}"
}

{
    "trade": {
        "offereeId": "{{player2Id}}",
        "id": "40bdf612-2546-41aa-a8cd-4e9b2eece9b1",
        "offerorId": "{{player1Id}}",
        "status": "accepted",
        "lines": [
            {
                "id": "cc7816b5-ad7c-4b77-9ef4-3830ab77b4e9",
                "tradeId": "40bdf612-2546-41aa-a8cd-4e9b2eece9b1",
                "playerId": "{{player1Id}}",
                "itemId": "{{NFTItemId}}",
                "quantity": "1"
            },
            {
                "id": "6a039fd2-922d-42da-99c4-b6101f7e6389",
                "tradeId": "40bdf612-2546-41aa-a8cd-4e9b2eece9b1",
                "playerId": "{{player2Id}}",
                "itemId": "{{FTItemId}}",
                "quantity": "1"
            }
        ]
    },
    "itemBalances": [
        {
            "playerId": "{{player1Id}}",
            "itemId": "{{FTItemId}}",
            "id": "3e28f9a3-a16c-4ba4-83a5-53e680863e4a",
            "amount": "1"
        },
        {
            "playerId": "{{player2Id}}",
            "itemId": "{{NFTItemId}}",
            "id": "afd09d82-8371-4f62-ab2d-8c8f336b747a",
            "amount": "1"
        },
        {
            "itemId": "{{FTItemId}}",
            "playerId": "{{player2Id}}",
            "amount": "0"
        }
    ]
}

Once the trade is accepted and executed, you will see the following item balance updates:

The offered NFT has moved to the offeree
The requested FT amount has been moved to the offerror
The requested FT amount has been removed from the offeree

Other Options

If either player does not agree to the contents of the trade, the trade can either be cancelled or declined.

Listing Trades

To view all of your trades, simply call the List Trades endpoint. With this endpoint, you have the ability to filter based on several options:

Offeror
Offeree
Status
Item Id
Collection Id