Docs / 02

Portfolio scan and health

Before the agents trade anything, they read what you hold. The scan works on any address, yours or someone else's, with no wallet connected and nothing signed: paste an address in the app or call the API. It returns every holding the agents can work with, valued, each coin graded, a health score from 0 to 100 and the moves the agents would make.

One scan: read, value, grade, score, propose.

What it reads

Native ETH, USDG and the 47 tokenized stocks, in one multicall.
Pons V2 coins: the balance of the wallet in each of the newest ~15,000 launches. The index comes from the Pons V2 factory's own TokenLaunched events and is kept current by the cron every fifteen minutes; an older coin can be added by hand with &coins=, since the scan does not look further back on its own.

How it values

Every price comes from a pool on the chain, read at the moment of the scan:

Holding	Priced from
ETH	The Uniswap v4 ETH/USDG pool, fee 500, no hook.
Stocks	The stock's deepest Uniswap v4 pool against ETH or USDG.
Pons coins on the curve	The reserves of the coin's own bonding curve.
Graduated Pons coins	The coin's Uniswap v4 pool with the Pons hook.
USDG	One dollar.

How it grades

Up to ten coins, the largest first, are graded by the case-file engine: a light case with the Census, the Locksmith and the Archivist, the same as the Night Watch files on the board. A grade is kept for two hours, then read again. Grades and their weights are described in Case files and grades.

An open case folder with pinned photographs and a magnifying glass

The health score

Health is 100 x (1 - penalty), where the penalty is the value-weighted sum of each coin's grade penalty, plus 0.1 when one coin is more than half the bag. Stocks, ETH and USDG carry no penalty.

Grade	A	B	C	D	E	Not graded
Penalty	0	0.1	0.35	0.7	1	0.5

A bag that is half a grade E coin and half stocks scores 50; the same bag with the coin swapped for USDG scores 100.

Proposed moves

The scan lists what the agents would do on a Balanced mandate, with the agent that calls each move and the reason:

Move	When	Called by
Cut	A coin graded D or E: sell all of it.	The Census
Trim	A coin graded C: sell half.	The Census
Take profit	A coin graded A or B that is over 25% of the bag: bring it down to 15%.	The Locksmith
Rotate	Coins are over 35% of the bag: move part into the top three stocks.	The Archivist
Deploy	ETH and USDG are over 40% of the bag: put part to work in the top three stocks.	The Archivist

The stock picks come with their reason, from the Archivist's ranking in The five agents at work. A scan proposes; nothing moves until you hand tokens to a vault.

The API

curl 'https://fixmybags.xyz/api/portfolio?address=0x…'
# optional: &coins=0x…,0x…  (older Pons coins to include)

{
  "owner": "0x…",
  "vault": "0x…" | null,
  "holdings": [ { "token", "symbol", "kind", "amount", "decimals", "usd", "grade", "phase", "route" } ],
  "total": 2024.04,
  "health": 45,
  "moves": [ { "agent", "action", "token", "symbol", "pct", "into", "why" } ],
  "picks": [ { "symbol", "name", "price", "why" } ]
}

vault is the wallet's own vault when it has one. A scan takes a few seconds for the balances and longer the first time a coin is graded.

Overview

The five agents at work