Guides

Marketplace

Suggest Edits

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.

Adding an Asset to the Marketplace

For an 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/assets/{the-id-of-the-asset}/sell.

curl --request POST \
     --url https://api.gameshift.dev/assets/exampleAssetId/sell \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: <your api key>' \
     --data '{"amountCents":1000}'

You must provide the following fields in the request body:

  • amountCents: In USD, the number of cents the user intends to sell the asset for

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

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:

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

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

Removing an Asset from the Marketplace

If an 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/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-sale>  
     --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.

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:

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

Purchasing an Asset from the Marketplace

Any 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/assets/{the-id-of-the-asset}/buy. 

curl --request POST  
     --url <https://api.gameshift.dev/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.

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 Assets 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/assets/for-sale. This will return a paginated list of assets and include details such as the assets’ current owner and the price it is listed at.

curl --request GET  
     --url <https://api.gameshift.dev/assets/for-sale>  
     --header 'accept: application/json'  
     --header 'x-api-key: <your api key>'

The response will look similar to this:

{  
  "data": [  
    {  
      "id": "050cda90-9567-45c7-93cc-aeea16a6572f",  
      "collection": {  
        "id": "4edb3273-5778-40bf-911f-fdaf40cb70be",  
        "name": "Example Collection",  
        "description": "An example of an asset collection",  
        "environment": "Development",  
        "imageUrl": "https://solana.com/src/img/branding/solanaLogoMark.png",  
        "imported": false,  
        "created": 1705619178060  
      },  
      "created": 1705641123922,  
      "attributes": [  
        {  
          "value": "1",  
          "traitType": "Trait 1"  
        },  
        {  
          "value": "2",  
          "traitType": "Trait 2"  
        },  
        {  
          "value": "3",  
          "traitType": "Trait 3"  
        }  
      ],  
      "name": "Example Asset",  
      "description": "An example of an asset",  
      "environment": "Development",  
      "escrow": true,  
      "imageUrl": "https://solana.com/src/img/branding/solanaLogoMark.png",  
      "imported": false,  
      "priceCents": 101,  
      "baseListingPrice": null,  
      "status": "Committed",  
      "mintAddress": "81X9rotqaydfTbPVivscpetrQq6kx1v3ZVi3tGbwnmC2",  
      "owner": {  
        "address": "6TS5MuTW9ekHxUdArHGCe2Yfa6uzZmJFmP5Ujppn8R2b",  
        "referenceId": "exampleUserId"  
      }  
    }
  ],  
  "meta": {  
    "page": 1,  
    "perPage": 50,  
    "totalPages": 1,  
    "totalResults": 8  
  }  
}

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 most likely safe for the transaction to fail multiple times, the only cost incurred is to external wallet users who pay for transaction fees.

Updated 9 months ago