Reading User Wallets

Fetching wallets is crucial because it allows you to see the contents of a wallet, including all tokens held within.

This is especially important in gaming and app development as it enables you to assign specific utilities or benefits to certain tokens.

For example, if a user has a particular token in their wallet, they might gain access to exclusive in-game items or features within an app, enhancing the user experience and adding value to the tokens.

What you'll need:

An Enjin Platform Account.

Best Practices

A token appears in a wallet's tokens list only while the wallet holds a balance of it, so the list always reflects the wallet's current holdings.
If you plan to utilize metadata from on-chain or external sources, it's important to also read the token's attributes. Typically, you'll find a uri attribute that points to the external location of this metadata.

Fetching a wallet with the Enjin API

Wallet data is read with the GetAccount query. It takes the network and chain to look up, along with the wallet's address.

SDKs are not yet available

The C# and C++ SDK examples below are out of date and will not work against the current Enjin Platform API. This section will be updated once new SDKs are published. Until then, use the GraphQL, cURL, Javascript, Node.js, or Python examples.

Fetching a wallet's Enjin Coin balance

Include the balance field in the GetAccount response to see how much ENJ a wallet holds.

Query:

query FetchWalletBalance{
  GetAccount(network: ENJIN, chain: MATRIX, address: "efQh8FzLm6oH3dmTU3HWqGrtm6Xcuu1WG33N2Ka9fzo5MFFAr"){ #Specify the network, chain, and account address
    balance
  }
}

curl --location 'https://platform.beta.enjin.io/graphql' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer enjin_api_key' \
-d '{"query":"query FetchWalletBalance($address: String!) {\r\n  GetAccount(network: ENJIN, chain: MATRIX, address: $address) {\r\n    balance\r\n  }\r\n}","variables":{"address":"efQh8FzLm6oH3dmTU3HWqGrtm6Xcuu1WG33N2Ka9fzo5MFFAr"}}'

using System.Text.Json;
using Enjin.Platform.Sdk;

// Setup the query
var getWallet = new GetWallet()
    .SetAccount("cxLU94nRz1en6gHnXnYPyTdtcZZ9dqBasexvexjArj4V1Qr8f");

// Define and assign the return data fragment to the query
var walletFragment = new WalletFragment()
    .WithBalances(new BalancesFragment()
        .WithFree()
        .WithReserved()
    );

getWallet.Fragment(walletFragment);

// Create and auth a client to send the request to the platform
var client = PlatformClient.Builder()
    .SetBaseAddress("https://platform.beta.enjin.io")
    .Build();
client.Auth("Your_Platform_Token_Here");

// Send the request and write the output to the console.
// Only the fields that were requested in the fragment will be filled in,
// other fields which weren't requested in the fragment will be set to null.
var response = await client.SendGetWallet(getWallet);
Console.WriteLine(JsonSerializer.Serialize(response.Result.Data));

#include "EnjinPlatformSdk/CoreQueries.hpp"
#include <iostream>

using namespace enjin::platform::sdk;
using namespace std;

int main() {

    // Set up the query
    GetWallet getWallet = GetWallet()
            .SetAccount(make_shared<SerializableString>("cxLU94nRz1en6gHnXnYPyTdtcZZ9dqBasexvexjArj4V1Qr8f"));

    // Define and assign the return data fragments to the query
    WalletFragment walletFragment = WalletFragment();
    BalancesFragment balancesFragment = BalancesFragment()
            .WithFree()
            .WithReserved();

    walletFragment.WithBalances(make_shared<BalancesFragment>(balancesFragment));

    getWallet.SetFragment(make_shared<WalletFragment>(walletFragment));

    // Create and auth a client to send the request to the platform
    unique_ptr<PlatformClient> client = PlatformClient::Builder()
            .SetBaseAddress("https://platform.beta.enjin.io")
            .Build();
    client->Auth("Your_Platform_Token_Here");

    // Send the request then get the response and write the output to the console.
    // Only the fields that were requested in the fragment will be filled in,
    // other fields which weren't requested in the fragment will be set to null.
    future<PlatformResponsePtr<GraphQlResponse<Wallet>>> futureResponse = SendGetWallet(*client, getWallet);

    // Get the platform response holding the HTTP data
    PlatformResponsePtr<GraphQlResponse<Wallet>> response = futureResponse.get();

    // Get the result, a GraphQL response, holding the GraphQL data
    const optional<GraphQlResponse<Wallet>>& gqlResult = response->GetResult();

    // Write the result data to the console
    if (gqlResult.has_value() && gqlResult->IsSuccess())
    {
        const optional<Wallet>& getWalletResult = gqlResult->GetData()->GetResult();

        std::cout << getWalletResult->GetBalances()->GetFree().value() << std::endl;
    }

    // Write any error messages to the console
    if (gqlResult.has_value() && gqlResult->HasErrors())
    {
        const optional<vector<GraphQlError>>& errors = gqlResult->GetErrors();

        for (const GraphQlError& error : errors.value()) {
            std::cout << error.GetMessage().value() << std::endl;
        }
    }

    client.reset();

    return 0;
}

fetch('https://platform.beta.enjin.io/graphql', {
  method: 'POST',
  headers: {'Content-Type': 'application/json','Authorization': 'Bearer Your_Platform_Token_Here'},
  body: JSON.stringify({
    query: `
      query FetchWalletBalance($address: String!) {
        GetAccount(network: ENJIN, chain: MATRIX, address: $address) {
          balance
        }
      }
    `,
    variables: {
      address: "efQh8FzLm6oH3dmTU3HWqGrtm6Xcuu1WG33N2Ka9fzo5MFFAr" //Specify the account address
    }
  }),
})
.then(response => response.json())
.then(data => console.log(data));

const axios = require('axios');

axios.post('https://platform.beta.enjin.io/graphql', {
  query: `
    query FetchWalletBalance($address: String!) {
      GetAccount(network: ENJIN, chain: MATRIX, address: $address) {
        balance
      }
    }
  `,
  variables: {
    address: "efQh8FzLm6oH3dmTU3HWqGrtm6Xcuu1WG33N2Ka9fzo5MFFAr" //Specify the account address
  }
}, {
  headers: {'Content-Type': 'application/json','Authorization': 'Bearer Your_Platform_Token_Here'}
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

import requests

query = '''
query FetchWalletBalance($address: String!) {
  GetAccount(network: ENJIN, chain: MATRIX, address: $address) {
    balance
  }
}
'''

variables = {
  'address': "efQh8FzLm6oH3dmTU3HWqGrtm6Xcuu1WG33N2Ka9fzo5MFFAr" #Specify the account address
}

response = requests.post('https://platform.beta.enjin.io/graphql',
  json={'query': query, 'variables': variables},
  headers={'Content-Type': 'application/json', 'Authorization': 'Bearer Your_Platform_Token_Here'}
)
print(response.json())

Response:

{
  "data": {
    "GetAccount": {
      "balance": "11799982990638599996" //~11.79998...  ENJ
    }
  }
}

Formatting Balances

The API returns the balance field in the base unit (u128), meaning it appears as a large integer without decimals. To obtain the readable ENJ amount, divide the returned value by 10^18.

Formula: Base Unit Value / 1,000,000,000,000,000,000 = ENJ Amount
Example: A value of 11799982990638599996 converts to approximately 11.80 ENJ.

Fetching the tokens a wallet holds

Include the tokens field in the GetAccount response to list every token the wallet currently holds. Each token also carries its parent collection, so this single query tells you which collections the wallet holds items in as well.

Query:

query FetchWalletTokens{
  GetAccount(network: ENJIN, chain: MATRIX, address: "efQh8FzLm6oH3dmTU3HWqGrtm6Xcuu1WG33N2Ka9fzo5MFFAr"){ #Specify the network, chain, and account address
    tokens{
      id
      tokenId
      collection{
        id
      }
      attributes{
        key
        value
      }
    }
  }
}

curl --location 'https://platform.beta.enjin.io/graphql' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer enjin_api_key' \
-d '{"query":"query FetchWalletTokens($address: String!) {\r\n  GetAccount(network: ENJIN, chain: MATRIX, address: $address) {\r\n    tokens {\r\n      id\r\n      tokenId\r\n      collection {\r\n        id\r\n      }\r\n      attributes {\r\n        key\r\n        value\r\n      }\r\n    }\r\n  }\r\n}","variables":{"address":"efQh8FzLm6oH3dmTU3HWqGrtm6Xcuu1WG33N2Ka9fzo5MFFAr"}}'

using System.Text.Json;
using Enjin.Platform.Sdk;

// Setup the query
var getWallet = new GetWallet()
    .SetAccount("cxLU94nRz1en6gHnXnYPyTdtcZZ9dqBasexvexjArj4V1Qr8f");

// Define and assign the return data fragment to the query
var walletFragment = new WalletFragment()
    .WithTokenAccounts(new ConnectionFragment<TokenAccountFragment>()
        .WithEdges(new EdgeFragment<TokenAccountFragment>()
            .WithNode(new TokenAccountFragment()
                .WithBalance()
                .WithToken(new TokenFragment()
                    .WithTokenId()
                    .WithCollection(new CollectionFragment()
                        .WithCollectionId()
                    )
                    .WithAttributes(new AttributeFragment()
                        .WithKey()
                        .WithValue()
                    )
                )
            )
        )
    );

getWallet.Fragment(walletFragment);

// Create and auth a client to send the request to the platform
var client = PlatformClient.Builder()
    .SetBaseAddress("https://platform.beta.enjin.io")
    .Build();
client.Auth("Your_Platform_Token_Here");

// Send the request and write the output to the console.
// Only the fields that were requested in the fragment will be filled in,
// other fields which weren't requested in the fragment will be set to null.
var response = await client.SendGetWallet(getWallet);
Console.WriteLine(JsonSerializer.Serialize(response.Result.Data));

#include "EnjinPlatformSdk/CoreQueries.hpp"
#include <iostream>

using namespace enjin::platform::sdk;
using namespace std;

int main() {

    // Set up the query
    GetWallet getWallet = GetWallet()
            .SetAccount(make_shared<SerializableString>("cxLU94nRz1en6gHnXnYPyTdtcZZ9dqBasexvexjArj4V1Qr8f"));

    // Define and assign the return data fragments to the query
    AccountFragment accountFragment = AccountFragment()
            .WithAddress();
    WalletFragment walletFragment = WalletFragment()
            .WithAccount(make_shared<AccountFragment>(accountFragment));
    AttributeFragment attributeFragment = AttributeFragment()
            .WithKey()
            .WithValue();
    CollectionFragment collectionFragment = CollectionFragment()
            .WithCollectionId();
    TokenFragment tokenFragment = TokenFragment()
            .WithTokenId()
            .WithCollection(make_shared<CollectionFragment>(collectionFragment))
            .WithAttributes(make_shared<AttributeFragment>(attributeFragment));
    TokenAccountFragment tokenAccountFragment = TokenAccountFragment()
            .WithBalance()
            .WithToken(make_shared<TokenFragment>(tokenFragment));

    EdgeFragment<TokenAccountFragment> edgeFragment = EdgeFragment<TokenAccountFragment>()
            .WithNode(make_shared<TokenAccountFragment>(tokenAccountFragment));

    ConnectionFragment<TokenAccountFragment> connectionFragment = ConnectionFragment<TokenAccountFragment>()
            .WithEdges(make_shared<EdgeFragment<TokenAccountFragment>>(edgeFragment));

    walletFragment.WithTokenAccounts(make_shared<ConnectionFragment<TokenAccountFragment>>(connectionFragment));

    getWallet.SetFragment(make_shared<WalletFragment>(walletFragment));

    // Create and auth a client to send the request to the platform
    unique_ptr<PlatformClient> client = PlatformClient::Builder()
            .SetBaseAddress("https://platform.beta.enjin.io")
            .Build();
    client->Auth("Your_Platform_Token_Here");

    // Send the request then get the response and write the output to the console.
    // Only the fields that were requested in the fragment will be filled in,
    // other fields which weren't requested in the fragment will be set to null.
    future<PlatformResponsePtr<GraphQlResponse<Wallet>>> futureResponse = SendGetWallet(*client, getWallet);

    // Get the platform response holding the HTTP data
    PlatformResponsePtr<GraphQlResponse<Wallet>> response = futureResponse.get();

    // Get the result, a GraphQL response, holding the GraphQL data
    const optional<GraphQlResponse<Wallet>>& gqlResult = response->GetResult();

    // Write the result data to the console
    if (gqlResult.has_value() && gqlResult->IsSuccess())
    {
        const optional<Wallet>& getWalletResult = gqlResult->GetData()->GetResult();

        std::cout << getWalletResult->GetAccount()->GetAddress().value() << std::endl;
    }

    // Write any error messages to the console
    if (gqlResult.has_value() && gqlResult->HasErrors())
    {
        const optional<vector<GraphQlError>>& errors = gqlResult->GetErrors();

        for (const GraphQlError& error : errors.value()) {
            std::cout << error.GetMessage().value() << std::endl;
        }
    }

    client.reset();

    return 0;
}

fetch('https://platform.beta.enjin.io/graphql', {
  method: 'POST',
  headers: {'Content-Type': 'application/json','Authorization': 'Bearer Your_Platform_Token_Here'},
  body: JSON.stringify({
    query: `
      query FetchWalletTokens($address: String!) {
        GetAccount(network: ENJIN, chain: MATRIX, address: $address) {
          tokens{
            id
            tokenId
            collection{
              id
            }
            attributes{
              key
              value
            }
          }
        }
      }
    `,
    variables: {
      address: "efQh8FzLm6oH3dmTU3HWqGrtm6Xcuu1WG33N2Ka9fzo5MFFAr" //Specify the account address
    }
  }),
})
.then(response => response.json())
.then(data => console.log(data));

const axios = require('axios');

axios.post('https://platform.beta.enjin.io/graphql', {
  query: `
    query FetchWalletTokens($address: String!) {
      GetAccount(network: ENJIN, chain: MATRIX, address: $address) {
        tokens{
          id
          tokenId
          collection{
            id
          }
          attributes{
            key
            value
          }
        }
      }
    }
  `,
  variables: {
    address: "efQh8FzLm6oH3dmTU3HWqGrtm6Xcuu1WG33N2Ka9fzo5MFFAr" //Specify the account address
  }
}, {
  headers: {'Content-Type': 'application/json','Authorization': 'Bearer Your_Platform_Token_Here'}
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

import requests

query = '''
query FetchWalletTokens($address: String!) {
  GetAccount(network: ENJIN, chain: MATRIX, address: $address) {
    tokens{
      id
      tokenId
      collection{
        id
      }
      attributes{
        key
        value
      }
    }
  }
}
'''

variables = {
  'address': "efQh8FzLm6oH3dmTU3HWqGrtm6Xcuu1WG33N2Ka9fzo5MFFAr" #Specify the account address
}

response = requests.post('https://platform.beta.enjin.io/graphql',
  json={'query': query, 'variables': variables},
  headers={'Content-Type': 'application/json', 'Authorization': 'Bearer Your_Platform_Token_Here'}
)
print(response.json())

Response:

{
  "data": {
    "GetAccount": {
      "tokens": [
        {
          "id": "2100-23",
          "tokenId": "23",
          "collection": {
            "id": "2100"
          },
          "attributes": [
            {
              "key": "uri",
              "value": "https://etherscapegame.com/crypto/Detritus.json?ver=2"
            }
          ]
        },
        {
          "id": "4265-1",
          "tokenId": "1",
          "collection": {
            "id": "4265"
          },
          "attributes": [
            {
              "key": "name",
              "value": "test 1"
            }
          ]
        },
        {
          "id": "4001-3",
          "tokenId": "3",
          "collection": {
            "id": "4001"
          },
          "attributes": []
        }
      ]
    }
  }
}

Each token's canonical id (for example 2100-23) combines its collection id and tokenId.

Explore More Arguments

For a comprehensive view of all available arguments for queries and mutations, please refer to our API Reference. This resource will guide you on how to use the GraphiQL Playground to explore the full structure and functionality of our API.

Fetching a wallet with the Enjin API​

Fetching a wallet's Enjin Coin balance​

Fetching the tokens a wallet holds​

Fetching a wallet with the Enjin API

Fetching a wallet's Enjin Coin balance

Fetching the tokens a wallet holds