Day 2: Read Wallet Balance and Transaction History

What You Will Learn Today

Why Are We Doing This?

Why can't I just look at Rabby to see my balance?

You are right. Rabby shows your balance perfectly.

But here is why we need code:

Imagine you are building the next Venmo or Cash App on Arc.

User opens your app. What do they see first?

"Your Balance: 127.50 USDC"


Your app needs to fetch this balance and display it in your own UI.

You cannot tell users: "Open Rabby in another tab to check your balance" - that is terrible UX.

What We Are Building

By the end of today, you will have scripts that:

This is the foundation of any payment app dashboard.

Prerequisites


Step 1: Navigate to Your Project Folder

Open Terminal in VS Code and run:

cd arc-project

Step 2: Check Your USDC Balance

Create the Balance Checker Script

  1. In VS Code, right-click your arc-project folder and select New File
  2. Name it: check-balance.ts
  3. Copy and paste this code:
import { createViemAdapterFromPrivateKey } from "@circle-fin/adapter-viem-v2";
import { createPublicClient, http, formatUnits, defineChain } from "viem";

const arcTestnet = defineChain({
  id: 5042002,
  name: "Arc Testnet",
  network: "arc-testnet",
  nativeCurrency: { name: "USDC", symbol: "USDC", decimals: 6 },
  rpcUrls: {
    default: { http: ["https://rpc.testnet.arc.network"] },
    public: { http: ["https://rpc.testnet.arc.network"] },
  },
});

const checkBalance = async () => {
  console.log("Checking your USDC balance on Arc Testnet\n");

  const adapter = createViemAdapterFromPrivateKey({
    privateKey: process.env.PRIVATE_KEY as string,
  });

  //  getAddress requires chain parameter
  const address = await adapter.getAddress({ chain: "Arc_Testnet" });
  console.log("Your wallet address:", address);
  console.log("----------------------------------\n");

  try {
    //  Use viem's getBalance directly instead of broken kit.getBalance
    const client = createPublicClient({ chain: arcTestnet, transport: http() });
    const raw = await client.getBalance({ address });
    
    //  Arc USDC uses 18 decimals, not 6
    const balance = formatUnits(raw, 18);

    console.log("Balance fetched successfully");
    console.log("----------------------------------");
    console.log("USDC Balance:", balance, "USDC");
    console.log("----------------------------------\n");

  } catch (error: any) {
    console.error("Error fetching balance:", error.message);
    console.log("\nTroubleshooting:");
    console.log("- Check your internet connection");
    console.log("- Verify your private key in .env file");
    console.log("- Make sure you are using Arc Testnet");
  }
};

checkBalance();
  1. Save the file (Ctrl+S)

Run the Script

npx tsx --env-file=.env check-balance.ts

Expected Output

Checking your USDC balance on Arc Testnet

Your wallet address: 0x6967b953509306348d42D541B4AA35d6aB1123AE
----------------------------------

Balance fetched successfully
----------------------------------
USDC Balance: 37.998877665544 USDC
----------------------------------

Step 3: Check Balance on Multiple Chains

Create Multi-Chain Balance Checker

  1. Right-click your arc-project folder and select New File
  2. Name it: multi-chain-balance.ts
  3. Copy and paste this code:
import { createViemAdapterFromPrivateKey } from "@circle-fin/adapter-viem-v2";
import { createPublicClient, http, formatUnits, defineChain } from "viem";
import { baseSepolia } from "viem/chains";

const arcTestnet = defineChain({
  id: 5042002,
  name: "Arc Testnet",
  network: "arc-testnet",
  nativeCurrency: { name: "USDC", symbol: "USDC", decimals: 6 },
  rpcUrls: {
    default: { http: ["https://rpc.testnet.arc.network"] },
    public: { http: ["https://rpc.testnet.arc.network"] },
  },
});

// Official Circle USDC on Base Sepolia
const BASE_SEPOLIA_USDC = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";

const ERC20_ABI = [{
  name: "balanceOf",
  type: "function",
  stateMutability: "view",
  inputs: [{ name: "account", type: "address" }],
  outputs: [{ name: "", type: "uint256" }],
}] as const;

const checkMultiChainBalance = async () => {
  console.log("Checking USDC balance across multiple chains\n");

  const adapter = createViemAdapterFromPrivateKey({
    privateKey: process.env.PRIVATE_KEY as string,
  });

  const address = await adapter.getAddress({ chain: "Arc_Testnet" });
  console.log("Wallet:", address);
  console.log("----------------------------------\n");

  // Arc Testnet — USDC is native token (18 decimals like ETH)
  const arcClient = createPublicClient({ chain: arcTestnet, transport: http() });
  const arcRaw = await arcClient.getBalance({ address });
  const arcBalance = formatUnits(arcRaw, 18);
  console.log(`Arc_Testnet:      ${arcBalance} USDC`);

  // Base Sepolia — USDC is ERC-20 (6 decimals)
  const baseClient = createPublicClient({ chain: baseSepolia, transport: http() });
  const baseRaw = await baseClient.readContract({
    address: BASE_SEPOLIA_USDC,
    abi: ERC20_ABI,
    functionName: "balanceOf",
    args: [address],
  });
  const baseBalance = formatUnits(baseRaw, 6);
  console.log(`Base_Sepolia:     ${baseBalance} USDC`);

  const total = parseFloat(arcBalance) + parseFloat(baseBalance);
  console.log("\n----------------------------------");
  console.log("Total USDC across all chains:", total.toFixed(2), "USDC");
  console.log("----------------------------------");
  console.log("\nThis is how Arc's Unified Balance works.");
  console.log("You can spend USDC from ANY chain in one transaction.");
};

checkMultiChainBalance();
  1. Save the file

Run It

npx tsx --env-file=.env multi-chain-balance.ts

Step 4: View Transaction History

Why Some Transactions Don't Show:

  1. Faucet/Mint Transactions: When you get USDC from the faucet, it's a MINT event (from zero address 0x000...000), not a regular Transfer. The code below shows these as "RECEIVED (Faucet/Mint)".
  2. Block Scan Range: We scan the last 50,000 blocks (~28 hours on Arc). Older transactions won't appear. View full history on the explorer.
  3. Base Sepolia Transactions from Rabby: If you transferred USDC in Rabby UI but see 0 results, the transaction happened but is outside the 50,000 block scan window. Check sepolia.basescan.org for the exact block number.

Create Transaction History Viewer

  1. Right-click your arc-project folder and select New File
  2. Name it: transaction-history.ts
  3. Copy and paste this code:
import { createViemAdapterFromPrivateKey } from "@circle-fin/adapter-viem-v2";
import { createPublicClient, http, formatUnits, defineChain, parseAbiItem } from "viem";
import { baseSepolia } from "viem/chains";

const arcTestnet = defineChain({
  id: 5042002,
  name: "Arc Testnet",
  network: "arc-testnet",
  nativeCurrency: { name: "USDC", symbol: "USDC", decimals: 6 },
  rpcUrls: {
    default: { http: ["https://rpc.testnet.arc.network"] },
    public: { http: ["https://rpc.testnet.arc.network"] },
  },
});

const BASE_SEPOLIA_USDC = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
const arcClient = createPublicClient({ chain: arcTestnet, transport: http() });
const baseClient = createPublicClient({ chain: baseSepolia, transport: http() });

const TRANSFER_EVENT = parseAbiItem(
  "event Transfer(address indexed from, address indexed to, uint256 value)"
);

// Fetch logs in chunks to stay under 10,000 block limit
const getLogsInChunks = async (
  client: any,
  address: `0x${string}`,
  fromBlock: bigint,
  toBlock: bigint,
  contractAddress?: `0x${string}`
) => {
  const CHUNK = 9000n;
  const allLogs: any[] = [];

  for (let start = fromBlock; start <= toBlock; start += CHUNK) {
    const end = start + CHUNK - 1n < toBlock ? start + CHUNK - 1n : toBlock;

    const [sent, received] = await Promise.all([
      client.getLogs({
        ...(contractAddress ? { address: contractAddress } : {}),
        event: TRANSFER_EVENT,
        fromBlock: start,
        toBlock: end,
        args: { from: address },
      }).catch(() => []),
      client.getLogs({
        ...(contractAddress ? { address: contractAddress } : {}),
        event: TRANSFER_EVENT,
        fromBlock: start,
        toBlock: end,
        args: { to: address },
      }).catch(() => []),
    ]);

    allLogs.push(...sent, ...received);
    process.stdout.write(".");
  }

  console.log(" done!\n");
  return allLogs.sort((a, b) => Number(b.blockNumber) - Number(a.blockNumber));
};

const getTransactionHistory = async (address: `0x${string}`) => {
  console.log("Wallet:", address);
  console.log("----------------------------------\n");

  // ── Arc Testnet ───────────────────────────────────────────────
  console.log("=== Arc Testnet USDC Transactions ===");
  process.stdout.write("Scanning");

  const arcLatest = await arcClient.getBlockNumber();
  const arcFrom = arcLatest > 50000n ? arcLatest - 50000n : 0n;

  const arcLogs = await getLogsInChunks(arcClient, address, arcFrom, arcLatest);

  if (arcLogs.length === 0) {
    console.log("No transactions found on Arc Testnet.");
    console.log(`View all: https://testnet.arcscan.app/address/${address}\n`);
  } else {
    console.log(`Found ${arcLogs.length} transaction(s):\n`);
    arcLogs.forEach((log: any, i: number) => {
      const dir = log.args.from?.toLowerCase() === address.toLowerCase() ? "SENT" : "RECEIVED";
      console.log(`#${i + 1} ${dir}`);
      console.log(`  From:   ${log.args.from}`);
      console.log(`  To:     ${log.args.to}`);
      console.log(`  Amount: ${formatUnits(log.args.value, 18)} USDC`);
      console.log(`  Block:  ${log.blockNumber}`);
      console.log(`  Hash:   ${log.transactionHash}`);
      console.log(`  View:   https://testnet.arcscan.app/tx/${log.transactionHash}\n`);
    });
  }

  // ── Base Sepolia ──────────────────────────────────────────────
  console.log("=== Base Sepolia USDC Transactions ===");
  process.stdout.write("Scanning");

  const baseLatest = await baseClient.getBlockNumber();
  const baseFrom = baseLatest > 50000n ? baseLatest - 50000n : 0n;

  const baseLogs = await getLogsInChunks(
    baseClient,
    address,
    baseFrom,
    baseLatest,
    BASE_SEPOLIA_USDC
  );

  if (baseLogs.length === 0) {
    console.log("No USDC transfers found on Base Sepolia.");
    console.log(`View all: https://sepolia.basescan.org/address/${address}\n`);
  } else {
    console.log(`Found ${baseLogs.length} transaction(s):\n`);
    baseLogs.forEach((log: any, i: number) => {
      const dir = log.args.from?.toLowerCase() === address.toLowerCase() ? "SENT" : "RECEIVED";
      console.log(`#${i + 1} ${dir}`);
      console.log(`  From:   ${log.args.from}`);
      console.log(`  To:     ${log.args.to}`);
      console.log(`  Amount: ${formatUnits(log.args.value, 6)} USDC`);
      console.log(`  Block:  ${log.blockNumber}`);
      console.log(`  Hash:   ${log.transactionHash}`);
      console.log(`  View:   https://sepolia.basescan.org/tx/${log.transactionHash}\n`);
    });
  }

  console.log("----------------------------------");
  console.log(`Full Arc history:  https://testnet.arcscan.app/address/${address}`);
  console.log(`Full Base history: https://sepolia.basescan.org/address/${address}`);
};

const adapter = createViemAdapterFromPrivateKey({
  privateKey: process.env.PRIVATE_KEY as string,
});

adapter.getAddress({ chain: "Arc_Testnet" }).then((address) => {
  getTransactionHistory(address as `0x${string}`);
});
  1. Save the file

Run It

npx tsx --env-file=.env transaction-history.ts

Transaction History Explanation:

This script scans the blockchain for Transfer events. Here's what shows and what doesn't:

Step 5: Create a Dashboard View

Build a Simple Dashboard

  1. Right-click your arc-project folder and select New File
  2. Name it: dashboard.ts
  3. Copy and paste this code:
import { createViemAdapterFromPrivateKey } from "@circle-fin/adapter-viem-v2";
import { createPublicClient, http, formatUnits, defineChain } from "viem";

const arcTestnet = defineChain({
  id: 5042002,
  name: "Arc Testnet",
  network: "arc-testnet",
  nativeCurrency: { name: "USDC", symbol: "USDC", decimals: 6 },
  rpcUrls: {
    default: { http: ["https://rpc.testnet.arc.network"] },
    public: { http: ["https://rpc.testnet.arc.network"] },
  },
});

const client = createPublicClient({
  chain: arcTestnet,
  transport: http(),
});

const showDashboard = async () => {
  const adapter = createViemAdapterFromPrivateKey({
    privateKey: process.env.PRIVATE_KEY as string,
  });

  const address = await adapter.getAddress({ chain: "Arc_Testnet" });

  const raw = await client.getBalance({ address });
  const balance = formatUnits(raw, 18);

  const latestBlock = await client.getBlockNumber();

  console.clear();
  console.log("\n");
  console.log("-----------------------------------------");
  console.log("         MY ARC PAYMENT APP");
  console.log("-----------------------------------------");
  console.log("\n");

  console.log("-------------------------------------------------");
  console.log("  Wallet");
  console.log(`  ${address.slice(0, 20)}...`);
  console.log("-------------------------------------------------");
  console.log("\n");

  console.log("-------------------------------------------------");
  console.log("  Your Balance");
  console.log("");
  console.log(`           ${balance} USDC`);
  console.log("");
  console.log("-------------------------------------------------");
  console.log("\n");

  console.log("-------------------------------------------------");
  console.log("  Quick Actions");
  console.log("");
  console.log("  [1] Send Money");
  console.log("  [2] Request Money");
  console.log("  [3] View History");
  console.log("  [4] Settings");
  console.log("");
  console.log("-------------------------------------------------");
  console.log("\n");

  console.log("-------------------------------------------------");
  console.log("  Network Status");
  console.log("");
  console.log(`  Chain: Arc Testnet`);
  console.log(`  Latest Block: ${latestBlock.toString()}`);
  console.log("  Status: Connected");
  console.log("");
  console.log("-------------------------------------------------");
  console.log("\n");

  console.log("This is what the data looks like in a real app.");
  console.log("In coming days, we will build the actual UI.\n");
};

showDashboard();
  1. Save the file

Run It

npx tsx --env-file=.env dashboard.ts

Your Project Folder Now

arc-project/
├── .env
├── package.json
├── node_modules/
├── transfer.ts              (from Day 1)
├── check-balance.ts         
├── multi-chain-balance.ts   
├── transaction-history.ts   
└── dashboard.ts             

What You Learned Today

Technical Skills

Concepts


Need Help?

Common issues:

  1. Balance shows wrong amount -> Wait 10 seconds and run again (blockchain needs time to update)
  2. Transaction history empty -> Send a transaction first (Day 1 script)
  3. Code will not run -> Check you are in the right folder (cd arc-project)

Useful Links

Key Takeaway

Every payment app has 3 core features:

  1. Show balance (Done today)
  2. Send money (Done Day 1)
  3. Transaction history (Done today)

You now have some for a basic payment app.

See you for Day 3!