Currencies (SPL Tokens)

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

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

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

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

curl --request POST \
     --url https://api.gamexx.dev/v2/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, GAMEXX 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.

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

curl --request GET \
     --url https://api.gamexx.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
  }
}

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

curl --request GET \
     --url https://api.gamexx.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
  }
}

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.gamexx.dev/users/{referenceId}/currencies/{currencyId}/transfer.

curl --request POST \
     --url https://api.gamexx.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.gamexx.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.gamexx.dev/consent?transaction=30aa77a1-bd5e-455a-898d-5345d0f058fc"
}