Portfolio

GET /api/portfolio/ gives you one account's total USD value at a single point in time, with a per-token breakdown. It's balance history, but rolled up across every token the account has ever touched.

Endpoint

Parameter	Required	Notes
`account_address`	yes	Wallet address
`at_time`	no	ISO-8601 timestamp; defaults to now

Example

Response

Code

json

1{
2  "success": true,
3  "data": {
4    "account_address": "0x00000005dd3d2f4429af886cd1a3b08289dbcea99a294197e9eb43b0e0325b4b",
5    "as_of": "2026-01-25T00:00:00+00:00",
6    "total_usd": 10490054.555862,
7    "tracked_total_usd": 10490054.555862,
8    "holdings_count": 44,
9    "untracked_count": 42,
10    "holdings": [
11      {
12        "token_address": "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8",
13        "balance": "5445937039751",
14        "balance_usd": 5445937.039751,
15        "token_price_usd": 1.0,
16        "symbol": "USDC",
17        "name": "USD Coin",
18        "logo": "https://...",
19        "decimals": 6,
20        "is_erc20": true,
21        "is_erc721": false,
22        "is_erc1155": false,
23        "verified": true,
24        "common": true,
25        "public": true,
26        "is_hidden": false
27      },
28      {
29        "token_address": "0x068f5c6a61780768455de69077e07e89787839bf8166decfbf92b645209c0fb8",
30        "balance": "5044117516111",
31        "balance_usd": 5044117.516111,
32        "token_price_usd": 1.0,
33        "symbol": "USDT",
34        "name": "Tether USD",
35        "logo": "https://...",
36        "decimals": 6,
37        "is_erc20": true,
38        "is_erc721": false,
39        "is_erc1155": false,
40        "verified": true,
41        "common": true,
42        "public": true,
43        "is_hidden": false
44      }
45    ]
46  }
47}

Holding entry fields

Each entry in holdings carries the on-chain balance plus a server-side join against the Token catalogue, so a wallet can render the row directly without a second round-trip to /api/tokens/.

Field	Type	Notes
`token_address`	string	Padded canonical form
`balance`	string	Raw on-chain integer (apply `decimals`)
`balance_usd`	number \| null	`null` for untracked tokens (no price feed)
`token_price_usd`	number \| null	The price used in `balance_usd`
`symbol`	string \| null	`Token.symbol`
`name`	string \| null	`Token.name`
`logo`	string \| null	`Token.logo`
`decimals`	number	`Token.decimals`; defaults to `18` if unknown
`is_erc20`	boolean
`is_erc721`	boolean	NFT collection
`is_erc1155`	boolean	Multi-token NFT
`verified`	boolean	`Token.verified` — we've manually reviewed this token
`common`	boolean	Curated set (USDC, USDT, ETH, STRK, ...)
`public`	boolean	`Token.public` — community-submitted / publicly listed
`is_hidden`	boolean	`Token.hidden` — we've flagged this token as not to be shown by default (suspected spam, malformed metadata, deduplication target). Wallets should filter these out unless the user opts into a "show hidden" mode.

Tracked vs. untracked

Field	What it means
`total_usd`	Sum of `balance_usd` across holdings we have a price for.
`tracked_total_usd`	Same as `total_usd`. The "we know what this is worth" subtotal, named explicitly.
`holdings_count`	How many (token, balance) pairs are non-zero at `at_time`.
`untracked_count`	How many of those holdings we don't have a price for.

Warning

Don't show total_usd on its own when a wallet has lots of untracked holdings. A wallet that's 90% long-tail meme tokens and 10% USDC will show a total_usd that wildly understates the real picture. Show the split: "$X tracked across N tokens / Y untracked".