Holdings and PnL on every chain
const url = 'https://api.getchord.xyz/v1/portfolio/example?chains=all&fresh=1';const options = {method: 'GET'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.getchord.xyz/v1/portfolio/example?chains=all&fresh=1'What one wallet holds on Chord’s eight EVM chains, and on Solana when you pass its Solana address, with its PnL over the last 24 hours, 7 days and 30 days. One rule for every chain, per token and window: the USD from its sales minus the USD of its buys inside the window, plus what is held now at today’s price, minus what was held at the window’s start at that hour’s close. No cost basis is involved, and transfers are neutral: a token that arrived by transfer only adds its price move, and a quantity bought in the window that left with no sale on the tape (sent, bridged out) counts as sold at the window’s average buy price, neither a gain nor a loss. Stablecoins are left out of PnL and counted in cashUsd.
Use it for: a wallet or portfolio page, “how did this wallet do this week”, an agent sizing a trade against what the wallet already holds.
Notes
- Coverage first. A window is
completeonly when the chain’s swap tape covers all of it. When it does not (the tape starts later, a hole in the history),usd,pctandfromTsare null: show a dash, never a partial number as a whole one. A total window is complete only when every chain in the answer is, chains that could not be read included. BNB Chain does not record swaps under $100: its windows still count as complete, andcoverage.ingestFloorUsdsays so. - Holdings = the chain’s token list plus every token the wallet swapped in the last 30 days, read on-chain (Solana: its 50 largest holdings). A token with no price Chord trusts (no measured liquidity, not on the chain’s board) has
priceUsd: null, comes last and is in no total. Priced holdings under $0.01 are folded intodust. - Each chain answers on its own deadline. One that cannot be read is
status: "unavailable"with areasoninside the 200 and is left out of the totals’ value;partial= the balances were read, part of the rest was not. - Times are milliseconds in this answer (
asOf,fromTs,tapeFromTs), unlike most of this API. - Cache: kept 45 seconds per wallet, Solana address and chain set (10 seconds when a chain could not be read); a copy up to 10 minutes old may be served once while a refresh runs (
asOfsays when it was computed).fresh=1recomputes, only for a request with anX-API-Keyor an Ask session; otherwise it is ignored. - Without an API key (or an Ask session): a cached answer is served to anyone. One IP may start at most 10 new reads every 10 minutes (this route and
/activitytogether), and every such caller together a limited number a minute; past either the answer is 429RATE_LIMITEDor 503BUSYwithRetry-After, and nothing is read. Send anX-API-Keyfor more.
Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”EVM address, hex, case-insensitive.
Query Parameters
Section titled “Query Parameters”Solana address, base58, case-sensitive. Never lower-case it.
The wallet’s Solana address. Adds Solana to the default scope.
all = the eight EVM chains, plus Solana when sol is given. Or a comma list of chain ids (143, 4663, 5042, 43114, 8453, 56, 42161, 1) and solana (which needs sol). Answered in registry order, Solana last. This route does not read chain: chain=5042 on its own still answers for every chain, so send chains=5042 for Arc alone.
Recompute instead of serving the cached answer. Honoured only with an X-API-Key or an Ask session.
Responses
Section titled “ Responses ”One wallet on every chain in scope.
object
EVM address, lower-case.
The Solana address as given, or null.
Unix time, milliseconds. When this answer was computed. A cached answer keeps its own asOf.
object
Sum of valueUsd over the chains that were read.
Complete only when every chain in the answer is complete for that window, chains that could not be read included. pct is the sum of the chains’ USD over the sum of their bases.
object
PnL over one window by the window rule (see GET /portfolio/{wallet}).
object
PnL over the window, USD. Null when the window is not complete.
Percent (1.5 = +1.5 %) of the base: the value held at the window’s start plus the USD bought in it. Null when that base is under one cent, or when the window is not complete.
The swap tape covers the whole window with no known hole. False = usd, pct and fromTs are null: show a dash, never a number.
Unix time, milliseconds. Where the number starts: the window’s start, aligned down to the hour. On totals: the latest start of the chains.
PnL over one window by the window rule (see GET /portfolio/{wallet}).
object
PnL over the window, USD. Null when the window is not complete.
Percent (1.5 = +1.5 %) of the base: the value held at the window’s start plus the USD bought in it. Null when that base is under one cent, or when the window is not complete.
The swap tape covers the whole window with no known hole. False = usd, pct and fromTs are null: show a dash, never a number.
Unix time, milliseconds. Where the number starts: the window’s start, aligned down to the hour. On totals: the latest start of the chains.
PnL over one window by the window rule (see GET /portfolio/{wallet}).
object
PnL over the window, USD. Null when the window is not complete.
Percent (1.5 = +1.5 %) of the base: the value held at the window’s start plus the USD bought in it. Null when that base is under one cent, or when the window is not complete.
The swap tape covers the whole window with no known hole. False = usd, pct and fromTs are null: show a dash, never a number.
Unix time, milliseconds. Where the number starts: the window’s start, aligned down to the hour. On totals: the latest start of the chains.
In registry order, Solana last.
One chain of a portfolio.
object
EVM chain id, or solana.
Registry key (monad, base, …) or solana.
ok = read. partial = balances read, part of the rest (prices, the tape, some tokens) not, and reason says which. unavailable = not read at all: in no total, every window without a number.
Present unless ok. One plain sentence for a person.
Sum of the priced holdings, small balances included.
The part of valueUsd held in stablecoins.
The chain’s PnL per window.
object
PnL over one window by the window rule (see GET /portfolio/{wallet}).
object
PnL over the window, USD. Null when the window is not complete.
Percent (1.5 = +1.5 %) of the base: the value held at the window’s start plus the USD bought in it. Null when that base is under one cent, or when the window is not complete.
The swap tape covers the whole window with no known hole. False = usd, pct and fromTs are null: show a dash, never a number.
Unix time, milliseconds. Where the number starts: the window’s start, aligned down to the hour. On totals: the latest start of the chains.
PnL over one window by the window rule (see GET /portfolio/{wallet}).
object
PnL over the window, USD. Null when the window is not complete.
Percent (1.5 = +1.5 %) of the base: the value held at the window’s start plus the USD bought in it. Null when that base is under one cent, or when the window is not complete.
The swap tape covers the whole window with no known hole. False = usd, pct and fromTs are null: show a dash, never a number.
Unix time, milliseconds. Where the number starts: the window’s start, aligned down to the hour. On totals: the latest start of the chains.
PnL over one window by the window rule (see GET /portfolio/{wallet}).
object
PnL over the window, USD. Null when the window is not complete.
Percent (1.5 = +1.5 %) of the base: the value held at the window’s start plus the USD bought in it. Null when that base is under one cent, or when the window is not complete.
The swap tape covers the whole window with no known hole. False = usd, pct and fromTs are null: show a dash, never a number.
Unix time, milliseconds. Where the number starts: the window’s start, aligned down to the hour. On totals: the latest start of the chains.
object
Unix time, milliseconds. First moment the chain’s swap tape covers without a hole for this wallet. Null = no tape here.
tape = Chord’s raw tape of the chain; tape+lake = older days joined from Chord’s history lake; box = Chord’s Solana index.
Present on a chain whose tape does not record swaps under this many USD (BNB Chain: 100). Disclosed, not a hole: that chain’s windows still count as complete, and a swap under the floor reads only as a price move or a transfer. Say so next to the numbers.
Priced holdings worth at least $0.01, largest first, then the unpriced ones.
One token a wallet holds on one chain.
object
EVM token, lower-case. Null for the chain’s native coin and on a Solana row (which carries mint).
Solana rows only: the mint, case kept.
From the chain’s list or the chain itself, never assumed.
The chain’s own coin (ETH, MON, AVAX, BNB, USDC on Arc, SOL).
A dollar stablecoin: counted in cashUsd, left out of PnL.
Balance in whole tokens, as a decimal string.
Null = no price Chord trusts (no measured liquidity, not on the chain’s board): listed last, in no total.
Amount × priceUsd.
Percent.
This token’s part of each window’s PnL, USD. Null = left out (a stablecoin, no price, no start price) or the chain’s window is not complete.
object
Priced holdings under $0.01, counted here and not listed.
object
Holdings with priceUsd: null (listed at the end of holdings).
Example
{ "chains": [ { "status": "ok", "coverage": { "source": "tape" } } ]}INVALID_ADDRESS (the wallet), INVALID_SOL_ADDRESS, BAD_CHAINS, or SOL_REQUIRED (chains names solana without sol).
Every non-2xx body.
object
Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.
For humans.
HTTP status, when included.
Example
{ "error": "INVALID_PARAMS", "message": "amount must be an integer string in the token's smallest unit"}RATE_LIMITED: without an API key, this IP started its 10 new portfolio reads of the last 10 minutes (Retry-After); a portfolio read in the last 10 minutes still answers. Or RATE_LIMIT_EXCEEDED, the per-minute limit of every route.
Every non-2xx body.
object
Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.
For humans.
HTTP status, when included.
Example
{ "error": "INVALID_PARAMS", "message": "amount must be an integer string in the token's smallest unit"}BUSY: too many new portfolio reads are running for callers without a key right now (Retry-After). UNAVAILABLE: the answer itself could not be built. A chain that cannot be read is not a 503: it comes back status: "unavailable" inside a 200.
Every non-2xx body.
object
Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.
For humans.
HTTP status, when included.
Example
{ "error": "INVALID_PARAMS", "message": "amount must be an integer string in the token's smallest unit"}