Guides

Currencies (SPL Tokens)

Import SPL Tokens to use within your game.

Suggest Edits

You can use GameShift to interact with SPL Tokens (called "Currencies" in GameShift) that are in your users' wallets or your developer wallet. You can view balances and initiate a request to transfer Currencies to other GameShift users or other Solana wallet addresses.

You cannot use GameShift to create any Currencies, but you can "import" existing Currencies into GameShift. In addition, GameShift user wallets can accept any valid SPL Tokens, however, in order to view balances via the GameShift API, you must first explicitly import the Currency. By default, GameShift auto-imports two commonly used Currencies: SOL and USDC.

Importing Currencies

Note: Importing Currencies will require a minor amount of Solana blockchain knowledge.

In order to import a Currency into GameShift, you can make a POST http request to https://api.gameshift.dev/v2/currencies/import.

curl --request POST \
     --url https://api.gameshift.dev/nx/currencies/import \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: <your api key>' \
     --data '
{
  "mintAddress": "Bb9bsTQa1bGEtQ5KagGkvSHyuLqDWumGUcRqFusFNJWC"
}
'

You must provide the following fields in the request body:

  • mintAddress: This is the address that defines the SPL Token you wish to import as a Currency.

The response will include some details about the Currency you just imported, including an id that you can use to refer to the Currency in other api requests.

{
  "id": "0a6fdc5c-5bef-4736-97ee-977d1ba952ab",
  "mintAddress": "Bb9bsTQa1bGEtQ5KagGkvSHyuLqDWumGUcRqFusFNJWC",
  "name": "Example Currency",
  "symbol": "EXMP"
}

If the Currency you imported has well defined metadata (such as a name and/or symbol), these will be picked up automatically. If not, GameShift will assign a default value to those fields in the form of an abbreviated mint address.

Currently, it is not possible to "un-import" a Currency.

Listing All Currencies

You can view all the Currencies currently registered to your game by making a GET http request to https://api.gameshift.dev/v2/currencies.

curl --request GET \
     --url https://api.gameshift.dev/v2/currencies \
     --header 'accept: application/json' \
     --header 'x-api-key: <your api key>'

The response will include a paginated list of Currencies you have previously imported. This list will not include the two default Currencies, SOL and USDC.

{
  "data": [
    {
      "id": "0a6fdc5c-5bef-4736-97ee-977d1ba952ab",
      "mintAddress": "Bb9bsTQa1bGEtQ5KagGkvSHyuLqDWumGUcRqFusFNJWC",
      "name": "Example Currency",
      "symbol": "EXMP"
    },
    {
      "id": "b3e6a7ff-d692-4843-8455-9f3777aae146",
      "mintAddress": "DuhbFTUND4Zv75bWbXtXthg2GLNNRvDGziYGZCR9EXFk",
      "name": "Diamonds",
      "symbol": "DMNDS"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 50,
    "totalPages": 1
  }
}

Viewing User Balances

You can view the balances of Currencies for any given user by making a GET http request to https://api.gameshift.dev/users/{referenceId}/currencies.

curl --request GET \
     --url https://api.gameshift.dev/users/example-user-id/currencies \
     --header 'accept: application/json' \
     --header 'x-api-key: <your api key>'

The response will include a paginated list of Currencies, and the quantity of each Currency possessed by the user. This response will also include the amount of SOL or USDC held by the user.

{
  "data": [
    {
      "amount": "1.1",
      "currency": {
        "id": "SOL",
        "mintAddress": "11111111111111111111111111111111",
        "name": "SOL",
        "symbol": "SOL"
      }
    },
    {
      "amount": "26.5",
      "currency": {
        "id": "USDC",
        "mintAddress": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
        "name": "USD Coin",
        "symbol": "USDC"
      }
    },
    {
      "amount": "10",
      "currency": {
        "id": "0a6fdc5c-5bef-4736-97ee-977d1ba952ab",
        "mintAddress": "Bb9bsTQa1bGEtQ5KagGkvSHyuLqDWumGUcRqFusFNJWC",
        "name": "Example Currency",
        "symbol": "EXMP"
      }
    },
    {
      "amount": "204",
      "currency": {
        "id": "b3e6a7ff-d692-4843-8455-9f3777aae146",
        "mintAddress": "DuhbFTUND4Zv75bWbXtXthg2GLNNRvDGziYGZCR9EXFk",
        "name": "Diamonds",
        "symbol": "DMNDS"
      }
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 50,
    "totalPages": 1
  }
}

Transferring Currencies

You can request a transfer of Currencies from one user to another, or to any on-chain Solana wallet address. The transfer of Currency will require the user's consent. To initiate a Currency transfer, you can make a POST http request to https://api.gameshift.dev/users/{referenceId}/currencies/{currencyId}/transfer.

curl --request POST \
     --url https://api.gameshift.dev/users/niranjan/currencies/0a6fdc5c-5bef-4736-97ee-977d1ba952ab/transfer \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: <your api key>' \
     --data '
{
  "amount": "1",
  "destinationUserReferenceId": "player-2"
}
'

If you wish to transfer SOL or USDC, the currencyId is "SOL" or "USDC" respectively.

curl --request POST \
     --url https://api.gameshift.dev/users/niranjan/currencies/USDC/transfer \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: <your api key>' \
     --data '
{
  "amount": "1",
  "destinationUserReferenceId": "player-2"
}
'

You must provide the following fields in the POST body:

  • amount: This is a string value that dictates how much of the Currency will be transferred.
  • destinationUserReferenceId OR destinationWallet: Identifies the recipient of the Currency.

All requests will return a "consent URL" that the user must visit to authorize the transfer of Currency.

{
  "url": "https://app.gameshift.dev/consent?transaction=30aa77a1-bd5e-455a-898d-5345d0f058fc"
}

Updated 8 months ago