Average buy and exits per token
const url = 'https://api.getchord.xyz/v1/portfolio/example/positions?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/positions?chains=all&fresh=1'What each token a wallet holds cost it, and what each token it sold made, over all the swap history Chord’s index holds for the wallet (not a 30-day window), with the wallet’s token transfers. Per token, in time order, three parts of the holding:
- bought by swap, at what was paid
- arrived by token transfer with a price on record at the hour it arrived (the median of the newest three hourly closes in the 24 hours before it), at that price
- unknown: arrived with no price, held before the history read, or a native coin received (no log)
A sale or a transfer out takes from the three parts in proportion to what each holds at that moment, so a sale is set only against what was held before it: a sale before the first buy is unmatchedSoldQty, and the average moves with each buy. A sale’s profit = its proceeds on the bought and arrived share minus that share’s cost; a transfer out makes no profit, its cost leaves with it. A wallet that holds more now than its flows explain held the rest from the start (unknown). At the end the parts are matched to the holding now.
heldBoughtQty+arrivedQty+receivedQty= the holding;investedUsd= the cost of the bought and arrived parts,avgBuyUsd= investedUsd / (heldBoughtQty + arrivedQty),pnlUsd= (heldBoughtQty + arrivedQty) × price − investedUsd- an exit’s
avgBuyUsd= the cost per token of what its sales took from the bought and arrived parts; (soldQty − unmatchedSoldQty) × avgBuyUsd is the costrealizedPctis a percent of
Use it for: “what did I pay for this”, “what did my exits make”, a positions tab next to GET /portfolio/{wallet}.
Notes
- History read: Monad, Robinhood Chain and Arc, the daily rollup of every day since the index started on the chain plus the raw tape of the recent days (never both for one day); Avalanche, Base, BNB Chain, Arbitrum One and Ethereum, the raw tape only (3 to 35 days; older days are not read yet, so a token bought before
fromTsreads as received). Each chain says where its history starts inchains[].fromTs. Solana: not yet (status: "unavailable"). EVM swaps under $0.10 are left out. - Limits: the newest 20,000 swaps of the raw tape and the 500 most traded tokens per chain; a chain that hits either is
partialwith areason. - Transfers: ERC-20 Transfer logs in and out of the wallet, read from the chain itself since the index start on Monad, Robinhood Chain and Arc, and since the first hourly price elsewhere; a transfer inside a swap the index holds is not counted twice, only what it moved beyond the swaps the index recorded for that transaction (or, before the raw tape, that day): a leg on a venue the index does not read arrives priced at that hour, a transfer tax or a liquidity deposit leaves. A wallet’s first reads on Arc are
partial(Transfers partial.) while the history is read in steps; at most 400 transfers per token and 4,000 per chain are counted, the newest first. - The native coin and its wrapped token are one asset to the tape: their history is split between the two rows by what each holds now, and an exit carries the coin’s name. Stablecoins have no row. A day of Monad, Robinhood Chain or Arc older than the raw tape is one row per token: its buys count at its first buying swap, its sales at its last selling swap.
- Times are milliseconds, quantities are numbers in whole tokens, and
amountis the portfolio’s decimal string. - Cache: kept 60 seconds per wallet, Solana address and chain set (15 seconds when a chain could not be read); a copy up to 5 minutes old may be served once while a refresh runs.
fresh=1recomputes, only with anX-API-Keyor an Ask session. - Without an API key (or an Ask session): a new read counts against the same budget as
GET /portfolio/{wallet}(10 new reads per IP every 10 minutes, a limited number a minute for every such caller together); past it 429RATE_LIMITEDor 503BUSYwithRetry-After.
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 ”What each held token cost and what each exit made, 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.
Every held token that is not a stablecoin, on a chain whose history was read, largest value first (unpriced last).
What one held token cost.
object
EVM chain id, or solana.
EVM token, lower-case. Null for the chain’s native coin.
Balance in whole tokens, decimal string (the portfolio’s).
InvestedUsd / (heldBoughtQty + arrivedQty): the cost per token of the part of the holding that has one. Null = no part has a cost.
What the held part with a cost cost: the bought part at what was paid, the arrived part at its price on arrival. Null = none.
(heldBoughtQty + arrivedQty) × priceUsd − investedUsd. Null = no cost behind the holding, or no price.
PnlUsd over investedUsd, a percent.
The part of the holding bought by swap, after what later sales and transfers out took from it.
The part that arrived by token transfer with a price on record at the hour it arrived; that price is its cost.
The cost of arrivedQty (quantity × price at arrival, after what later left). Null when arrivedQty is 0.
Unix time, milliseconds. The newest priced arrival. Null when arrivedQty is 0.
The part with no cost known: arrived with no price on record, held before the history read, or a native coin received (no log). In no PnL. heldBoughtQty + arrivedQty + receivedQty = the holding.
Profit on what was sold, by the closed rule. Null = nothing sold, or no sale took from a part with a cost.
Swap totals (transfers are not buys or sells).
Unix time, milliseconds.
Unix time, milliseconds.
Every token that is not a stablecoin sold in part or in full, newest last sale first, at most 100.
What one exit made: a token sold in part or in full.
object
EVM chain id, or solana.
EVM token, lower-case. Null for the chain’s native coin (its wrapped twin is the same asset).
Nothing held now, or less than $1 of it.
Sold out of the part with no cost known, or beyond what was held on record at the time (a sale before the first buy): no profit is counted on it.
Cost per token of what the sales took from the parts with a cost; (soldQty − unmatchedSoldQty) × avgBuyUsd is the cost realizedPct is a percent of.
Per sale, its proceeds on the part with a cost minus that part’s cost, summed. Null = no sale took from a part with a cost.
RealizedUsd over (soldQty − unmatchedSoldQty) × avgBuyUsd, a percent.
Unix time, milliseconds.
Unix time, milliseconds.
object
Sum of the open rows’ pnlUsd. Null when a chain in scope could not be read (its holdings, or their history while it holds a priced token).
Sum of realizedUsd over every exit, the ones past the first 100 included.
Sum of the open rows’ investedUsd.
Exits with realizedUsd above zero.
Exits with realizedUsd below zero.
In registry order, Solana last.
One chain of a positions answer.
object
EVM chain id, or solana.
ok = every swap Chord’s index holds for the wallet on this chain, and its token transfers, were read. partial = some were cut, and reason says which (for example Transfers not read. or Transfers partial.: the numbers stand on the swaps and the transfers that were read). unavailable = nothing read: no open or closed rows for this chain (Solana: not yet).
Present unless ok. One plain sentence for a person.
Unix time, milliseconds. Swaps from here on are in the index for this chain: a buy before it reads as received. Null = no swap history read.
Example
{ "chains": [ { "status": "ok" } ]}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 positions read in the last 5 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"}