Your first app

A short script that reads a wallet's coins, lists its latest transactions and prints a plain sentence for each.

Set up

You need Node 20 or newer. Make a folder, add the script, and run it with tsx.

Shell

mkdir tide-wallet && cd tide-wallet
npm init -y
npm i -D tsx
export TIDE_API_KEY=tide_YOUR_KEY   # optional: without it the keyless tier is used

The script

wallet.ts

// wallet.ts: print a wallet's coins and a plain sentence for its latest transactions.
const API = "https://api.tide.ad";
const headers: Record<string, string> = { "content-type": "application/json" };
if (process.env.TIDE_API_KEY) headers["x-api-key"] = process.env.TIDE_API_KEY;

async function get(path: string) {
  const res = await fetch(API + path, { headers });
  if (!res.ok) throw new Error(`${res.status} ${JSON.stringify(await res.json())}`);
  return res.json();
}

const wallet = process.argv[2];
if (!wallet) throw new Error("usage: tsx wallet.ts <address or name.sui>");

// 1. What the wallet holds, in USD.
const bal = await get(`/v1/wallet/${encodeURIComponent(wallet)}/balances?limit=5`);
console.log(`Total: $${Number(bal.totalUsdValue ?? 0).toFixed(2)}`);
for (const c of bal.balances) console.log(`  ${c.symbol}  ${c.balance}  $${Number(c.usdValue ?? 0).toFixed(2)}`);

// 2. Its latest transactions.
const hist = await get(`/v1/wallet/${encodeURIComponent(wallet)}/history?limit=3`);
const digests: string[] = hist.data.map((t: { digest: string }) => t.digest);

// 3. Ask tide to explain them.
const res = await fetch(API + "/v0/transactions", { method: "POST", headers, body: JSON.stringify({ transactions: digests }) });
const parsed = await res.json();
for (const t of parsed) console.log(`${new Date(t.timestamp * 1000).toISOString()}  ${t.type}  ${t.description}`);

Run it

Shell

npx tsx wallet.ts 0x671f7079e238edf837ae8d4fe8274f3337e1b20bbc08e2e9b9b7f5fcee9566e2

The argument can also be a SuiNS name, such as example.sui.

How it works

GET /v1/wallet/:wallet/balances returns every coin with its USD value. See wallet.balances.
GET /v1/wallet/:wallet/history returns transactions newest first with a cursor for the next page. See wallet.history.
POST /v0/transactions turns digests into typed transactions with a description. See tx.parse. It costs 1 credit per transaction.

Every answer includes an asOf field, so you always know which checkpoint it is true at.

Where next

History and holders at any date: run the same wallet at a past date.
Pagination, cursors and asOf: read the whole history, not just the first page.
Wallets: identity, PnL and positions.