# Average buy and exits per token

`GET https://api.getchord.xyz/v1/portfolio/{wallet}/positions`

Source: https://getchord.xyz/docs/api-reference/operations/portfoliopositions/

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

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `wallet` | path | yes | string |  |
| `sol` | query | no | string | The wallet's Solana address. Adds Solana to the default scope. |
| `chains` | query | no | 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` | query | no | `1` | Recompute instead of serving the cached answer. Honoured only with an `X-API-Key` or an Ask session. |

## Response 200

- **400**: `INVALID_ADDRESS` (the wallet), `INVALID_SOL_ADDRESS`, `BAD_CHAINS`, or `SOL_REQUIRED` (`chains` names `solana` without `sol`).
- **429**: `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.
- **503**: `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.
