Tokens - Ralph Studio

The indexer tracks all tokens issued on Alephium, both fungible tokens (FTs) and non-fungible tokens (NFTs). These endpoints let you fetch metadata, holder lists, transfer history, and price information where available.

Get token metadata

Returns metadata for a fungible token by its contract address.

curl "https://rpc.ralphstudio.xyz/{slug}/indexer/tokens/{token-id}" \
  -H "Authorization: Bearer API_KEY"

{
  "id": "b2d71c116408ae47a83c6db0571a1b2d1f58dc87ac5d7e8e4c2a3d1f9e0b8c4",
  "symbol": "USDT",
  "name": "Tether USD",
  "decimals": 6,
  "totalSupply": "1000000000000"
}

Tokens that have not registered metadata on-chain will return only id and totalSupply. Always check for the presence of symbol and name before rendering.

Get all fungible tokens

Returns a paginated list of all known fungible tokens on the network.

curl "https://rpc.ralphstudio.xyz/{slug}/indexer/tokens/fungible-tokens?page=1&limit=20" \
  -H "Authorization: Bearer API_KEY"

{
  "tokens": [
    {
      "id": "b2d71c...",
      "symbol": "USDT",
      "name": "Tether USD",
      "decimals": 6,
      "totalSupply": "1000000000000"
    },
    {
      "id": "c3e82d...",
      "symbol": "WBTC",
      "name": "Wrapped Bitcoin",
      "decimals": 8,
      "totalSupply": "21000000000000000"
    }
  ],
  "total": 84
}

Get all NFT collections

Returns a paginated list of known NFT collections.

curl "https://rpc.ralphstudio.xyz/{slug}/indexer/tokens/nft-collections?page=1&limit=20" \
  -H "Authorization: Bearer API_KEY"

{
  "collections": [
    {
      "address": "27Gsc5...",
      "collectionUri": "https://metadata.example.com/collection.json",
      "totalSupply": "1000"
    }
  ],
  "total": 12
}

Get NFT metadata

Returns metadata for a single NFT by its token contract address.

curl "https://rpc.ralphstudio.xyz/{slug}/indexer/tokens/{token-id}/nft" \
  -H "Authorization: Bearer API_KEY"

{
  "id": "d4f93e...",
  "collectionAddress": "27Gsc5...",
  "nftIndex": "42",
  "tokenUri": "https://metadata.example.com/42.json",
  "image": "https://images.example.com/42.png",
  "name": "Alephium Punk #42",
  "description": "A unique punk on Alephium."
}

nftIndex is the position of this NFT within its collection contract. tokenUri points to the off-chain JSON metadata, the indexer does not cache the contents of that URI.

Get token transactions

Returns paginated transfer history for a token across all addresses.

curl "https://rpc.ralphstudio.xyz/{slug}/indexer/tokens/{token-id}/transactions?page=1&limit=20" \
  -H "Authorization: Bearer API_KEY"

[
  {
    "hash": "503a2c...",
    "blockHash": "00000000ab3c...",
    "timestamp": 1748476800000,
    "inputs": [...],
    "outputs": [...],
    "gasAmount": 20000,
    "gasPrice": "100000000000",
    "scriptExecutionOk": true
  }
]

Get token holders

Returns the top holders of a fungible token sorted by balance descending.

curl "https://rpc.ralphstudio.xyz/{slug}/indexer/tokens/{token-id}/addresses?page=1&limit=20" \
  -H "Authorization: Bearer API_KEY"

{
  "holders": [
    {
      "address": "1DrDyTr9...",
      "balance": "500000000000",
      "lockedBalance": "0"
    },
    {
      "address": "1AujpupF...",
      "balance": "250000000000",
      "lockedBalance": "0"
    }
  ],
  "total": 312
}

Get NFTs in a collection

Returns all NFTs belonging to a specific collection contract.

curl "https://rpc.ralphstudio.xyz/{slug}/indexer/tokens/nft-collections/{collection-address}/nfts?page=1&limit=20" \
  -H "Authorization: Bearer API_KEY"

{
  "nfts": [
    {
      "id": "d4f93e...",
      "nftIndex": "0",
      "tokenUri": "https://metadata.example.com/0.json"
    },
    {
      "id": "e5a04f...",
      "nftIndex": "1",
      "tokenUri": "https://metadata.example.com/1.json"
    }
  ],
  "total": 1000
}

Distinguishing FTs from NFTs

The indexer does not tag a token as FT or NFT in every response. A reliable way to tell them apart:

function isNFT(token) {
  // NFTs always have a supply of exactly 1
  return token.totalSupply === "1";
}

function formatAmount(rawAmount, decimals) {
  // Fungible tokens use fixed-point amounts
  return Number(rawAmount) / Math.pow(10, decimals);
}

If decimals is missing from the metadata response, treat the token as an NFT candidate and fetch /tokens/{id}/nft to confirm.

Building a token portfolio view

Combine the address tokens endpoint with the metadata endpoint to render a full portfolio:

const BASE = "https://rpc.ralphstudio.xyz/{slug}/indexer";
const API_KEY = "API_KEY";

async function getPortfolio(address) {
  // Step 1: get all token balances for the address
  const holdingsRes = await fetch(`${BASE}/addresses/${address}/tokens`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const holdings = await holdingsRes.json();

  // Step 2: fetch metadata for each token in parallel
  const withMeta = await Promise.all(
    holdings.map(async (holding) => {
      const metaRes = await fetch(`${BASE}/tokens/${holding.tokenId}`, {
        headers: { Authorization: `Bearer ${API_KEY}` },
      });
      const meta = await metaRes.json();
      return {
        ...holding,
        symbol: meta.symbol ?? holding.tokenId.slice(0, 8),
        name: meta.name ?? "Unknown Token",
        decimals: meta.decimals ?? 0,
        formattedBalance: meta.decimals
          ? Number(holding.balance) / Math.pow(10, meta.decimals)
          : holding.balance,
      };
    }),
  );

  return withMeta;
}

For production use, cache the metadata responses, token metadata is immutable once set on-chain and does not change.

Parameters reference

Parameter	Type	Description
token-id	string	Token contract address
collection-address	string	NFT collection contract address
page	integer	Page number (default: 1)
limit	integer	Results per page (default: 20, max: 100)

​Get token metadata

​Get all fungible tokens

​Get all NFT collections

​Get NFT metadata

​Get token transactions

​Get token holders

​Get NFTs in a collection

​Distinguishing FTs from NFTs

​Building a token portfolio view

​Parameters reference