Skip to content

Average buy and exits per token

GET
/portfolio/{wallet}/positions
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 cost realizedPct is 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 fromTs reads as received). Each chain says where its history starts in chains[].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 partial with a reason.
  • 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 amount is 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=1 recomputes, only with an X-API-Key or 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 429 RATE_LIMITED or 503 BUSY with Retry-After.
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

What each held token cost and what each exit made, 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
open

Every held token that is not a stablecoin, on a chain whose history was read, largest value first (unpriced last).

Array<object>

What one held token cost.

object
chain

EVM chain id, or solana.

integer | string
address

EVM token, lower-case. Null for the chain’s native coin.

string | null
symbol
string
logo
string | null
amount

Balance in whole tokens, decimal string (the portfolio’s).

string
priceUsd
number | null
valueUsd
number | null
avgBuyUsd

InvestedUsd / (heldBoughtQty + arrivedQty): the cost per token of the part of the holding that has one. Null = no part has a cost.

number | null
investedUsd

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.

number | null
pnlUsd

(heldBoughtQty + arrivedQty) × priceUsd − investedUsd. Null = no cost behind the holding, or no price.

number | null
pnlPct

PnlUsd over investedUsd, a percent.

number | null
heldBoughtQty

The part of the holding bought by swap, after what later sales and transfers out took from it.

number
arrivedQty

The part that arrived by token transfer with a price on record at the hour it arrived; that price is its cost.

number
arrivedUsd

The cost of arrivedQty (quantity × price at arrival, after what later left). Null when arrivedQty is 0.

number | null
lastArrivalTs

Unix time, milliseconds. The newest priced arrival. Null when arrivedQty is 0.

integer | null
receivedQty

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.

number
realizedUsd

Profit on what was sold, by the closed rule. Null = nothing sold, or no sale took from a part with a cost.

number | null
boughtQty

Swap totals (transfers are not buys or sells).

number
boughtUsd
number
soldQty
number
soldUsd
number
buys
integer
sells
integer
firstBuyTs

Unix time, milliseconds.

integer | null
lastTradeTs

Unix time, milliseconds.

integer | null
closed

Every token that is not a stablecoin sold in part or in full, newest last sale first, at most 100.

Array<object>

What one exit made: a token sold in part or in full.

object
chain

EVM chain id, or solana.

integer | string
address

EVM token, lower-case. Null for the chain’s native coin (its wrapped twin is the same asset).

string | null
symbol
string
name
string | null
logo
string | null
soldAll

Nothing held now, or less than $1 of it.

boolean
soldQty
number
boughtQty
number
unmatchedSoldQty

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.

number
avgBuyUsd

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.

number | null
avgSellUsd
number | null
realizedUsd

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.

number | null
realizedPct

RealizedUsd over (soldQty − unmatchedSoldQty) × avgBuyUsd, a percent.

number | null
firstBuyTs

Unix time, milliseconds.

integer | null
lastSellTs

Unix time, milliseconds.

integer
totals
object
openPnlUsd

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

number | null
closedPnlUsd

Sum of realizedUsd over every exit, the ones past the first 100 included.

number
investedUsd

Sum of the open rows’ investedUsd.

number
won

Exits with realizedUsd above zero.

integer
lost

Exits with realizedUsd below zero.

integer
chains

In registry order, Solana last.

Array<object>

One chain of a positions answer.

object
chain
required

EVM chain id, or solana.

integer | string
status
required

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

string
Allowed values: ok partial unavailable
reason

Present unless ok. One plain sentence for a person.

string
fromTs
required

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.

integer | null
Example
{
"chains": [
{
"status": "ok"
}
]
}

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 positions read in the last 5 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"
}