GameShift’s marketplace APIs make it easy to maintain a peer-to-peer marketplace for in-game collectibles. Through the API, your players will be able to list assets for sale, remove assets from the marketplace, and purchase assets from other players using a credit card. You can render all marketplace activity in your game, so that players never need to leave the game to trade.

Unique Assets

Adding a Unique Asset to the Marketplace

For a Unique Asset to be listed on the marketplace, you’ll first need to capture the consent of the asset's current owner. To list an asset, you can make a POST http request to https://api.gameshift.dev/nx/unique-assets/{the-id-of-the-asset}/list-for-sale.

curl --request POST \
     --url https://api.gameshift.dev/nx/unique-assets/exampleAssetId/list-for-sale \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: <your api key>' \
     --data '
{
  "price": {
    "currencyId": "USDC",
    "naturalAmount": "10"
  }
}
'

You must provide the following fields in the request body:

price.currencyId: Specifies the currency. Currently, only USDC is supported
price.naturalAmount: The amount to charge for the asset

All requests will return a “consent URL” that you must navigate the user to in order to complete listing the asset for sale.

{
  "transactionId": "726e9605-fd51-47f2-a183-97261027799f",
  "consentUrl": "https://app.gameshift.dev/consent?transaction=726e9605-fd51-47f2-a183-97261027799f"
}

Once the user completes the consent flow, the asset will be transferred to the marketplace program in escrow until it is purchased or the listing is canceled by the seller. The asset will still appear as owned by the user in the Fetch User Assets API. Any asset with an active marketplace listing will have the following properties set:

forSale: true: Indicates that the asset is currently being held in escrow on the marketplace
price: The price the item was listed at by the seller

When the asset is purchased, the seller will receive the price.naturalAmount in USDC, deposited to their GameShift wallet. The seller can then transfer their USDC to another address or withdraw it to their bank account.

Cancelling a Unique Asset Listing

If a unique asset is already listed on the marketplace, you can delist it. This will require the consent of the asset owner. To delist the asset, you can make a POST http request to https://api.gameshift.dev/nx/unique-assets/{the-id-of-the-asset}/cancel-sale. There are no additional fields required in the request body.

curl --request POST  
     --url https://api.gameshift.dev/assets/exampleAssetId/cancel-listing  
     --header 'accept: application/json'  
     --header 'x-api-key: <your api key>'

All requests will return a “consent URL” that you must navigate the user to in order to finish removing the asset from the marketplace.

{
  "transactionId": "726e9605-fd51-47f2-a183-97261027799f",
  "consentUrl": "https://app.gameshift.dev/consent?transaction=726e9605-fd51-47f2-a183-97261027799f"
}

Once the user completes the consent flow, the asset listing will be canceled and the asset will be released from the marketplace program escrow. The following properties of the asset will revert to its pre-listed values:

forSale: false: Indicates that the asset is no longer being held in escrow.
price: null: An item removed from the marketplace will not have a price.

Purchasing a Unique Asset from the Marketplace

Any Unique Asset on the marketplace can be purchased by your users. The user will complete the purchase with a credit card, and they will also need to provide consent for the transaction. Both are handled by a “consent URL” you must navigate the user to.

In order to initiate a purchase from the marketplace (and receive a consent URL to navigate the user to), you can make a POST http request to https://api.gameshift.dev/nx/unique-assets/{the-id-of-the-asset}/buy.

curl --request POST  
     --url https://api.gameshift.dev/nx/unique-assets/exampleAssetId/buy  
     --header 'accept: application/json'  
     --header 'content-type: application/json'  
     --header 'x-api-key: <your api key>'  
     --data '  
{  
  "buyerId": "exampleBuyerId"  
}  
'

You must provide the following fields in the request body:

buyerId: This is the reference id of the user making the purchase

All requests will return a “consent URL” that you must navigate the user to in order to complete purchasing the asset.

{
  "transactionId": "726e9605-fd51-47f2-a183-97261027799f",
  "consentUrl": "https://app.gameshift.dev/consent?transaction=726e9605-fd51-47f2-a183-97261027799f"
}

The user will first be prompted to enter their credit card information. After their card is successfully charged, they will be prompted to approve an on-chain transaction to execute the purchase transaction with the on-chain marketplace program. Following this, the asset will be released to the buyer’s GameShift wallet.

Retrieving All Items Currently Listed for Sale on the Marketplace

You can get a list of all assets currently listed on the marketplace by making a GET http request to https://api.gameshift.dev/nx/items?forSale=true. This utilizes query parameter filters on the "Get Many Items" endpoint.

curl --request GET  
     --url https://api.gameshift.dev/nx/items?forSale=true
     --header 'accept: application/json'  
     --header 'x-api-key: <your api key>'

The response will look similar to this:

{
  "data": [
    {
      "type": "UniqueAsset",
      "item": {
        "id": "5036c3f0-16f5-4212-9601-773b348558b7",
        "collection": {
          "id": "76ce1359-2124-40f1-b011-a97316ac9e03",
          "name": "Example Collection",
          "description": "This is an example",
          "environment": "Development",
          "imageUrl": "https://cloudflare-ipfs.com/ipfs/QmWsnbRQV8vYCSkrVU8uvgQeSnkiD9MLZv2kmuKDUXh2VC",
          "imported": false,
          "mintAddress": "AUFD3zYELr4BJh1A7vqsVtuGELRQxeJVNG55zyizDynS",
          "created": 1701965780057
        },
        "created": 1707935037900,
        "attributes": [
          {
            "value": "Example Value",
            "traitType": "example-trait"
          }
        ],
        "name": "Example Asset",
        "description": "This is an example asset",
        "environment": "Development",
        "forSale": true,
        "imageUrl": "https://solana.com/src/img/branding/solanaLogoMark.png",
        "imported": false,
        "price": {
          "currencyId": "USDC",
          "naturalAmount": "2000"
        },
        "status": "Committed",
        "mintAddress": "H9qXqvCetS3wJ7x7n8ynfWG9cEQjyCQyWEA1kCLyaXhs",
        "owner": {
          "address": "qYpoPgN3NnTKN5zdCzcbyaQYpyp13cHyQdKke8fHMep",
          "referenceId": "exampleUserId"
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 50,
    "totalPages": 1,
    "totalResults": 1
  }
}

What happens when a user pays with their credit card?

Certain purchase flows on GameShift require two user steps: first, completing the fiat payment step; and, second, signing a transaction to complete an on-chain purchase with the funds delivered from the first step. It is possible that the second step fails to complete because the user rejects the transaction, it times out, or the asset that the user is attempting to purchase is no longer available.

In the case of a transaction rejection or time out, the user can reload the page and they will see a balance of "Coinflow Credits" which can be used to retry the on-chain transaction. After a short period of time (typically less than one hour), these credits will be eliminated and the fiat transaction from step one will be reversed. The process also prevents the user from being double-charged for the purchase.

If the user's transaction fails, it is the developer's responsibility to investigate the root cause. In most cases, it will be because the asset has been already bought by another user, or the listing has been canceled. However, it is safe for the transaction to fail multiple times, the only cost incurred is to external wallet users who pay for transaction fees.