Assets & Chains

The Sphere Assets service provides comprehensive information about supported blockchain networks (chains) and tokens. This service allows you to:

• Query all supported chains and tokens
• Get detailed information about specific assets
• Filter tokens by chain
• View user-specific asset information (authenticated)

Overview

The Assets service offers both public endpoints (no authentication required) and authenticated endpoints that provide user-specific information. This makes it easy to discover what assets are available on the platform and which ones a specific user owns.

Prerequisites

import Sphere, {
  Environment,
  WalletChain,
  WalletToken,
  ApiResponse,
} from "@stratosphere/wallet";

const sphere = new Sphere({
  apiKey: "YOUR_API_KEY",
  environment: Environment.DEVELOPMENT,
});

// For authenticated endpoints, you'll need a user's access token
// sphere.setBearerToken("USER_ACCESS_TOKEN");

1. Supported Chains

Get All Supported Chains (Public)

Retrieve a list of all blockchain networks supported by Sphere.

async function getAllSupportedChains(): Promise<WalletChain[] | null> {
  try {
    const response = await sphere.assets.getSupportedChains();

    if (response.data) {
      console.log(`Found ${response.data.length} supported chains:`);
      response.data.forEach((chain) => {
        console.log(`\n  Chain: ${chain.name}`);
        console.log(`  ID: ${chain.id}`);
        console.log(`  Enabled: ${chain.enabled}`);
        if (chain.description)
          console.log(`  Description: ${chain.description}`);
      });
      return response.data;
    }
    return null;
  } catch (error) {
    console.error("Error fetching supported chains:", error);
    throw error;
  }
}

// Example usage:
getAllSupportedChains().then((chains) => {
  // Use chains data in your application
});

Get User's Active Chains (Authenticated)

Retrieve only the chains where the authenticated user has active balances.

async function getUserActiveChains(): Promise<WalletChain[] | null> {
  if (!sphere.isAuthenticated()) {
    console.error("User must be authenticated to fetch active chains");
    return null;
  }

  try {
    // Pass true to get only active chains
    const response = await sphere.assets.getSupportedChains(true);

    if (response.data) {
      console.log(`User has assets on ${response.data.length} chains:`);
      response.data.forEach((chain) => {
        console.log(`  - ${chain.name} (${chain.id})`);
      });
      return response.data;
    }
    return null;
  } catch (error) {
    console.error("Error fetching user's active chains:", error);
    throw error;
  }
}

Get Specific Chain Details

Retrieve detailed information about a specific blockchain by its ID.

async function getChainDetails(chainId: string): Promise<WalletChain | null> {
  try {
    const response = await sphere.assets.getChainById(chainId);

    if (response.data) {
      console.log(`Chain Details for ID ${chainId}:`);
      console.log(`  Name: ${response.data.name}`);
      console.log(`  Enabled: ${response.data.enabled}`);
      if (response.data.description) {
        console.log(`  Description: ${response.data.description}`);
      }
      return response.data;
    }
    return null;
  } catch (error) {
    console.error(`Error fetching chain ${chainId}:`, error);
    throw error;
  }
}

// Example usage:
getChainDetails("1"); // Get Ethereum mainnet details

2. Token Management

Get All Available Tokens (Public)

Retrieve a comprehensive list of all tokens supported across all chains.

async function getAllTokens(): Promise<WalletToken[] | null> {
  try {
    const response = await sphere.assets.getAllTokens();

    if (response.data) {
      console.log(`Total tokens available: ${response.data.length}`);

      // Group tokens by chain for better organization
      const tokensByChain = response.data.reduce((acc, token) => {
        if (!acc[token.chain_id]) acc[token.chain_id] = [];
        acc[token.chain_id].push(token);
        return acc;
      }, {} as Record<string, WalletToken[]>);

      Object.entries(tokensByChain).forEach(([chainId, tokens]) => {
        console.log(`\nChain ${chainId}: ${tokens.length} tokens`);
        tokens.forEach((token) => {
          console.log(`  - ${token.name} (${token.id})`);
        });
      });

      return response.data;
    }
    return null;
  } catch (error) {
    console.error("Error fetching all tokens:", error);
    throw error;
  }
}

Get User's Tokens (Authenticated)

Retrieve only the tokens that the authenticated user owns.

async function getUserOwnedTokens(): Promise<WalletToken[] | null> {
  if (!sphere.isAuthenticated()) {
    console.error("User must be authenticated to fetch owned tokens");
    return null;
  }

  try {
    const response = await sphere.assets.getUserTokens();

    if (response.data) {
      console.log(`User owns ${response.data.length} different tokens:`);
      response.data.forEach((token) => {
        console.log(`\n  Token: ${token.name}`);
        console.log(`  ID: ${token.id}`);
        console.log(`  Chain: ${token.chain_id}`);
        if (token.contract_address) {
          console.log(`  Contract: ${token.contract_address}`);
        }
      });
      return response.data;
    }
    return null;
  } catch (error) {
    console.error("Error fetching user tokens:", error);
    throw error;
  }
}

Get Tokens by Chain

Retrieve all tokens available on a specific blockchain.

async function getTokensForChain(
  chainId: string
): Promise<WalletToken[] | null> {
  try {
    const response = await sphere.assets.getTokensByChainId(chainId);

    if (response.data) {
      console.log(`Tokens available on chain ${chainId}:`);
      response.data.forEach((token) => {
        console.log(`\n  ${token.name} (${token.id})`);
        console.log(`    Enabled: ${token.enabled}`);
        if (token.contract_address) {
          console.log(`    Contract: ${token.contract_address}`);
        } else {
          console.log(`    Native token`);
        }
      });
      return response.data;
    }
    return null;
  } catch (error) {
    console.error(`Error fetching tokens for chain ${chainId}:`, error);
    throw error;
  }
}

// Example usage:
getTokensForChain("1"); // Get all Ethereum tokens
getTokensForChain("137"); // Get all Polygon tokens

Get Specific Token Details

Retrieve detailed information about a specific token using its ID.

async function getTokenDetails(tokenId: string): Promise<WalletToken | null> {
  try {
    const response = await sphere.assets.getTokenById(tokenId);

    if (response.data) {
      console.log(`Token Details for ${tokenId}:`);
      console.log(`  Name: ${response.data.name}`);
      console.log(`  Chain ID: ${response.data.chain_id}`);
      console.log(`  Enabled: ${response.data.enabled}`);
      if (response.data.contract_address) {
        console.log(`  Contract Address: ${response.data.contract_address}`);
      } else {
        console.log(`  Type: Native token`);
      }
      if (response.data.description) {
        console.log(`  Description: ${response.data.description}`);
      }
      return response.data;
    }
    return null;
  } catch (error) {
    console.error(`Error fetching token ${tokenId}:`, error);
    throw error;
  }
}

// Example usage with proper token ID format:
getTokenDetails("ETHEREUM-USDC"); // USDC on Ethereum
getTokenDetails("POLYGON-MATIC"); // MATIC on Polygon
getTokenDetails("ETHEREUM-ETH"); // Native ETH on Ethereum

Type Definitions

WalletChain

interface WalletChain {
  id: string; // Numeric chain ID as string (e.g., "1" for Ethereum)
  name: string; // Human-readable chain name
  description?: string; // Optional chain description
  icon?: string; // Optional icon URL
  enabled: boolean; // Whether the chain is currently enabled
}

WalletToken

interface WalletToken {
  id: string; // Token ID format: CHAINNAME-SYMBOL (e.g., "ETHEREUM-USDC")
  name: string; // Human-readable token name
  description?: string; // Optional token description
  enabled: boolean; // Whether the token is currently enabled
  contract_address?: string | null; // Smart contract address (null for native tokens)
  chain_id: string; // ID of the chain this token belongs to
  icon?: string; // Optional icon URL
}

ApiResponse

interface ApiResponse<T> {
  data: T; // The response data
  message?: string; // Optional status message
  success?: boolean; // Success indicator
}

Important Considerations

• Token ID Format: Token IDs follow the format CHAINNAME-SYMBOL (e.g., "ETHEREUM-USDC", "POLYGON-MATIC"). Always use uppercase for both chain name and symbol.

• Authentication Requirements:

  • Public endpoints: getSupportedChains(), getAllTokens(), getTokensByChainId(), getTokenById(), getChainById()
  • Authenticated endpoints: getSupportedChains(true), getUserTokens()

• Native vs Contract Tokens: Native tokens (like ETH on Ethereum, MATIC on Polygon) will have contract_address as null. ERC-20 and other token standards will have a contract address.

• Chain IDs: Chain IDs are provided as strings but represent the numeric chain identifiers (e.g., "1" for Ethereum mainnet, "137" for Polygon).

• Enabled Status: Both chains and tokens have an enabled flag. Only interact with assets where enabled: true.

Complete Example

Here's a comprehensive example showing how to discover and work with assets:

async function exploreAssetsForUser() {
  try {
    // First, check what chains are available
    const allChains = await sphere.assets.getSupportedChains();
    console.log(`Platform supports ${allChains.data?.length} chains`);

    // Authenticate user (assume we have their token)
    sphere.setBearerToken("USER_ACCESS_TOKEN");

    // Get chains where user has assets
    const userChains = await sphere.assets.getSupportedChains(true);
    console.log(`User has assets on ${userChains.data?.length} chains`);

    // For each active chain, get the user's tokens
    if (userChains.data) {
      for (const chain of userChains.data) {
        const tokens = await sphere.assets.getTokensByChainId(chain.id);
        console.log(`\n${chain.name} supports ${tokens.data?.length} tokens`);

        // Get detailed info for a specific token if needed
        if (tokens.data && tokens.data.length > 0) {
          const tokenDetails = await sphere.assets.getTokenById(
            tokens.data[0].id
          );
          console.log(`First token details:`, tokenDetails.data);
        }
      }
    }

    // Get all tokens owned by the user across all chains
    const userTokens = await sphere.assets.getUserTokens();
    console.log(
      `\nUser owns ${userTokens.data?.length} different tokens total`
    );
  } catch (error) {
    console.error("Error exploring assets:", error);
  }
}

Next Steps

• Use the Assets service to populate token/chain selectors in your UI
• Filter available tokens based on user's active chains
• Validate token/chain combinations before transactions
• Check Wallet Balances for specific asset amounts
• Proceed to Send Transactions with discovered assets

---

For more information about supported assets or to request new token/chain additions, consult the Sphere documentation or contact support.