This is the first guide in our series on building a realtime, multichain wallet using Sim APIs.
In this one, we will lay the foundation for our wallet.
You will set up a Node project with Express.js, fetch and display token balances from 60+ EVM chains using the Balances API, and calculate the wallet's total portfolio value in USD.
<% if (tokens && tokens.length > 0) { %>
<% tokens.forEach(token => { %>
<% if (token.token_metadata && token.token_metadata.logo) { %>
<% } else { %>
<% } %>
<% }); %>
<% } else if (walletAddress) { %>
<% if (token.token_metadata && token.token_metadata.url) { %>
<%= token.name || token.symbol %>
<% } else { %><%= token.name || token.symbol %>
<% } %><%= token.valueUSDFormatted || (token.value_usd != null ? token.value_usd : 'N/A') %>
<%= token.amountFormatted || token.amount %> <%= token.symbol %>
No tokens found for this wallet.
<% } else { %>Enter a wallet address above to see token balances.
<% } %>Activity feature will be added in the next guide.
Collectibles feature will be added in a future guide.
## Format Balances
The Balances API returns token amounts in their smallest denomination. This will be in wei for ETH-like tokens.
To display these amounts in a user-friendly way, like `1.23` ETH instead of `1230000000000000000` wei, we need to adjust the amount using the token's `decimals` property, which is also returned from the Balances API.
We can add a new property, `balanceFormatted`, to each token object.
Modify your `getWalletBalances` function in `server.js` as follows. The main change is mapping over `data.balances` to add the `balanceFormatted` property:
```javascript server.js (getWalletBalances with formatting) {24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38} theme={null}
async function getWalletBalances(walletAddress) {
if (!walletAddress) return [];
const queryParams = `metadata=url,logo`;
const url = `https://api.sim.dune.com/v1/evm/balances/${walletAddress}?${queryParams}`;
try {
const response = await fetch(url, {
headers: {
'X-Sim-Api-Key': SIM_API_KEY,
'Content-Type': 'application/json'
}
});
if (!response.ok) {
const errorBody = await response.text();
console.error(`API request failed with status ${response.status}: ${response.statusText}`, errorBody);
throw new Error(`API request failed: ${response.statusText}`);
}
const data = await response.json();
// Return formatted values and amounts
return (data.balances || []).map(token => {
// 1. Calculate human-readable token amount
const numericAmount = parseFloat(token.amount) / Math.pow(10, parseInt(token.decimals));
// 2. Get numeric USD value
const numericValueUSD = parseFloat(token.value_usd);
// 3. Format using numbro
const valueUSDFormatted = numbro(numericValueUSD).format('$0,0.00');
const amountFormatted = numbro(numericAmount).format('0,0.[00]A');
return {
...token,
valueUSDFormatted,
amountFormatted
};
}).filter(token => token.symbol !== 'RTFKT'); // Removing Spam Tokens. Add more if you like.
} catch (error) {
console.error("Error fetching wallet balances:", error.message);
return [];
}
}
```
Now, each token object returned by `getWalletBalances` will include a `balanceFormatted` string, which our EJS template (`views/wallet.ejs`) already uses: `<%= token.balanceFormatted || token.amount %>`.
Restart the server and refresh the browser. You will now see formatted balances.
## Calculate Total Portfolio Value
The wallet's total value at the top of the UI still says `$0.00`.
Let's calculate the total USD value of the wallet and properly show it.
The Balances API provides a `value_usd` field with each token.
This field represents the total U.S. dollar value of the wallet's entire holding for that specific token.
Let's modify the `app.get('/')` route handler to iterate through the fetched tokens and sum their individual `value_usd` to calculate the `totalWalletUSDValue`.
```javascript server.js (app.get('/') with total value calculation) {16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 37} theme={null}
app.get('/', async (req, res) => {
const {
walletAddress = '',
tab = 'tokens'
} = req.query;
let tokens = [];
let totalWalletUSDValue = 0; // Will be updated
let errorMessage = null;
if (walletAddress) {
try {
tokens = await getWalletBalances(walletAddress);
// Calculate the total USD value from the fetched tokens
if (tokens && tokens.length > 0) {
tokens.forEach(token => {
let individualValue = parseFloat(token.value_usd);
if (!isNaN(individualValue)) {
totalWalletUSDValue += individualValue;
}
});
}
totalWalletUSDValue = numbro(totalWalletUSDValue).format('$0,0.00');
} catch (error) {
console.error("Error in route handler:", error);
errorMessage = "Failed to fetch wallet data. Please try again.";
// tokens will remain empty, totalWalletUSDValue will be 0
}
}
res.render('wallet', {
walletAddress: walletAddress,
currentTab: tab,
totalWalletUSDValue: totalWalletUSDValue, // Pass the calculated total
tokens: tokens,
activities: [], // Placeholder for Guide 2
collectibles: [], // Placeholder for Guide 3
errorMessage: errorMessage
});
});
```
We use the `reduce` method to iterate over the `tokens` array.
For each `token`, we access its `value_usd` property, parse it as a float, and add it to the running `sum`.
The calculated `totalWalletUSDValue` is then formatted to two decimal places and passed to the template.
The `views/wallet.ejs` template already has `
## Add Historical Price Tracking
Now let's improve the wallet by showing price movement over time. Historical price context helps users understand how their tokens are gaining or losing value. The [Balances API](/evm/balances) can return historical price points when you include the `historical_prices` query parameter, which lets you display price changes for any hour offset from 1 to 24 hours ago.
