Skip to content

Holdings and PnL on every chain

GET
/portfolio/{wallet}
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 complete only when the chain’s swap tape covers all of it. When it does not (the tape starts later, a hole in the history), usd, pct and fromTs are 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, and coverage.ingestFloorUsd says 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 into dust.
  • Each chain answers on its own deadline. One that cannot be read is status: "unavailable" with a reason inside 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 (asOf says when it was computed). fresh=1 recomputes, only for a request with an X-API-Key or 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 /activity together), and every such caller together a limited number a minute; past either the answer is 429 RATE_LIMITED or 503 BUSY with Retry-After, and nothing is read. Send an X-API-Key for more.
wallet
required

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/
sol

Solana address, base58, case-sensitive. Never lower-case it.

string
/^[1-9A-HJ-NP-Za-km-z]{32,44}$/

The wallet’s Solana address. Adds Solana to the default scope.

chains
string
default: all

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.

fresh
string
Allowed values: 1

Recompute instead of serving the cached answer. Honoured only with an X-API-Key or an Ask session.

Media typeapplication/json

One wallet on every chain in scope.

object
wallet

EVM address, lower-case.

string
/^0x[a-fA-F0-9]{40}$/
sol

The Solana address as given, or null.

string | null
/^[1-9A-HJ-NP-Za-km-z]{32,44}$/
asOf

Unix time, milliseconds. When this answer was computed. A cached answer keeps its own asOf.

integer
totals
object
valueUsd

Sum of valueUsd over the chains that were read.

number
cashUsd
number
pnl

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
24h
required

PnL over one window by the window rule (see GET /portfolio/{wallet}).

object
usd
required

PnL over the window, USD. Null when the window is not complete.

number | null
pct
required

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.

number | null
complete
required

The swap tape covers the whole window with no known hole. False = usd, pct and fromTs are null: show a dash, never a number.

boolean
fromTs
required

Unix time, milliseconds. Where the number starts: the window’s start, aligned down to the hour. On totals: the latest start of the chains.

integer | null
7d
required

PnL over one window by the window rule (see GET /portfolio/{wallet}).

object
usd
required

PnL over the window, USD. Null when the window is not complete.

number | null
pct
required

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.

number | null
complete
required

The swap tape covers the whole window with no known hole. False = usd, pct and fromTs are null: show a dash, never a number.

boolean
fromTs
required

Unix time, milliseconds. Where the number starts: the window’s start, aligned down to the hour. On totals: the latest start of the chains.

integer | null
30d
required

PnL over one window by the window rule (see GET /portfolio/{wallet}).

object
usd
required

PnL over the window, USD. Null when the window is not complete.

number | null
pct
required

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.

number | null
complete
required

The swap tape covers the whole window with no known hole. False = usd, pct and fromTs are null: show a dash, never a number.

boolean
fromTs
required

Unix time, milliseconds. Where the number starts: the window’s start, aligned down to the hour. On totals: the latest start of the chains.

integer | null
chains

In registry order, Solana last.

Array<object>

One chain of a portfolio.

object
chain

EVM chain id, or solana.

integer | string
key

Registry key (monad, base, …) or solana.

string
name
string
status

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.

string
Allowed values: ok partial unavailable
reason

Present unless ok. One plain sentence for a person.

string
valueUsd

Sum of the priced holdings, small balances included.

number
cashUsd

The part of valueUsd held in stablecoins.

number
pnl

The chain’s PnL per window.

object
24h
required

PnL over one window by the window rule (see GET /portfolio/{wallet}).

object
usd
required

PnL over the window, USD. Null when the window is not complete.

number | null
pct
required

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.

number | null
complete
required

The swap tape covers the whole window with no known hole. False = usd, pct and fromTs are null: show a dash, never a number.

boolean
fromTs
required

Unix time, milliseconds. Where the number starts: the window’s start, aligned down to the hour. On totals: the latest start of the chains.

integer | null
7d
required

PnL over one window by the window rule (see GET /portfolio/{wallet}).

object
usd
required

PnL over the window, USD. Null when the window is not complete.

number | null
pct
required

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.

number | null
complete
required

The swap tape covers the whole window with no known hole. False = usd, pct and fromTs are null: show a dash, never a number.

boolean
fromTs
required

Unix time, milliseconds. Where the number starts: the window’s start, aligned down to the hour. On totals: the latest start of the chains.

integer | null
30d
required

PnL over one window by the window rule (see GET /portfolio/{wallet}).

object
usd
required

PnL over the window, USD. Null when the window is not complete.

number | null
pct
required

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.

number | null
complete
required

The swap tape covers the whole window with no known hole. False = usd, pct and fromTs are null: show a dash, never a number.

boolean
fromTs
required

Unix time, milliseconds. Where the number starts: the window’s start, aligned down to the hour. On totals: the latest start of the chains.

integer | null
coverage
object
tapeFromTs

Unix time, milliseconds. First moment the chain’s swap tape covers without a hole for this wallet. Null = no tape here.

integer | null
source

tape = Chord’s raw tape of the chain; tape+lake = older days joined from Chord’s history lake; box = Chord’s Solana index.

string
Allowed values: tape tape+lake box
ingestFloorUsd

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.

number | null
holdings

Priced holdings worth at least $0.01, largest first, then the unpriced ones.

Array<object>

One token a wallet holds on one chain.

object
address

EVM token, lower-case. Null for the chain’s native coin and on a Solana row (which carries mint).

string | null
mint

Solana rows only: the mint, case kept.

string
symbol
string
name
string | null
decimals

From the chain’s list or the chain itself, never assumed.

integer
logo
string | null
native

The chain’s own coin (ETH, MON, AVAX, BNB, USDC on Arc, SOL).

boolean
stable

A dollar stablecoin: counted in cashUsd, left out of PnL.

boolean
amount

Balance in whole tokens, as a decimal string.

string
priceUsd

Null = no price Chord trusts (no measured liquidity, not on the chain’s board): listed last, in no total.

number | null
valueUsd

Amount × priceUsd.

number | null
change24hPct

Percent.

number | null
pnl

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
24h
required
number | null
7d
required
number | null
30d
required
number | null
dust

Priced holdings under $0.01, counted here and not listed.

object
count
integer
valueUsd
number
unpriced

Holdings with priceUsd: null (listed at the end of holdings).

integer
Example
{
"chains": [
{
"status": "ok",
"coverage": {
"source": "tape"
}
}
]
}

INVALID_ADDRESS (the wallet), INVALID_SOL_ADDRESS, BAD_CHAINS, or SOL_REQUIRED (chains names solana without sol).

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
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.

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
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.

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
Example
{
"error": "INVALID_PARAMS",
"message": "amount must be an integer string in the token's smallest unit"
}