> ## Documentation Index > Fetch the complete documentation index at: https://docs.raze.bot/llms.txt > Use this file to discover all available pages before exploring further. # Positions in a token > What each wallet did with this token over the last 365 days and holds now: buys and sells, amounts and USD in and out at the time of each swap, average buy price, realized profit, unrealized profit at the token's current `priceUsd` (the same price `/tokens` gives), first and last trade. A swap shows up within seconds. Fields are `null` when the source does not know the token, or a figure could not be measured. Figures are the wallet-stats source's; `/tokens/{chain}/{address}/traders` is another source's view of its top traders and can differ. Rows come in the order asked (a wallet asked twice comes twice). To follow a wallet live, read again on its `balance` frame of the [`wallet` channel](/streaming/channels#wallet), no sooner than 3 s after the previous read. Up to 10 wallets' positions in one token in one call (`wallets=w1,w2,…`), in the order asked: what each did with the token over the last 365 days and holds now. * `buys`, `sells`, `boughtAmount`, `soldAmount`, `boughtUsd` and `soldUsd`: the wallet's swaps of the token, in USD at the time of each swap. A route through the token counts both legs. * `avgBuyPriceUsd` is the plain average (`boughtUsd` / `boughtAmount`). * `realizedPnlUsd` is the profit on what was sold; `unrealizedPnlUsd` the tokens bought and still held at `priceUsd` (the price `/tokens` gives), less their cost; `totalPnlUsd` the two together. * `valueUsd` is `balance` × `priceUsd` only when the token has a pool of at least \$1,000 (as [holdings](/api-reference/wallets/holdings)). * A figure the source could not measure is `null`, never `0`. The figures come from the source behind the [wallet stats](/api-reference/wallets/get); [top traders](/api-reference/tokens/traders) is another source's view and can differ. A swap shows up within seconds: to follow a wallet live, read again on its `balance` frame of the [`wallet` channel](/streaming/channels#wallet), no sooner than 3 s after the previous read. ## OpenAPI ````yaml GET /tokens/{chain}/{address}/positions openapi: 3.1.0 info: title: Raze Market Data API version: 1.0.0 description: > Multichain market data for tokens, trades, charts, holders, launchpads and wallets on Solana, Ethereum, BNB Chain, Base and Robinhood Chain, as REST snapshots and live streams. **Conventions, everywhere:** - Chains: `sol`, `eth`, `bsc`, `base`, `robinhood`, in any case (aliases `solana`, `ethereum`, `mainnet`, `bnb`, `binance`, `hood`, `rh` and network ids work too). Answers always use the slug. - EVM addresses are answered lowercase; Solana addresses are case-sensitive. - Amounts in USD end in `Usd`; percents are 0–100 and end in `Percent`; times are Unix **milliseconds**. - A value nobody knows is `null`, never `0`. - Success: `{"data": …}`, plus `"next"` on paged lists (pass it back as `cursor`, as given). A page can hold fewer rows than `limit`, even none, and still carry `next`: a list ends only where `next` is `null`. A `limit` above a route's maximum is capped, not refused. - Failure: `{"error": {"code", "message"}}` with status 400 (`bad_request`), 401 (`unauthorized`), 404 (`not_found`), 429 (`rate_limited`), or 503 with a `Retry-After` header (`upstream_unavailable` when a source could not be read: ask again after it, with the same parameters and cursor; `server_busy` on a new live connection while the server is at capacity). One exception: a query value of the wrong type (`limit=abc`) is a 400 with a plain-text body. - A trade, wallet-trade or retract row has an `id`: key rows on it. Every image field is an https URL an `` can load, or `null` (also for a URL pointing at a private, loopback or link-local address, itself or through a URL in its query). - A Solana address that does not decode to a 32-byte key is a 400 wherever one token or wallet is named. Lists (`/tokens?ids=`, `/prices?tokens=`) leave out an id that looks like a Solana address (32 to 44 base58 characters) but is not a 32-byte key; an id that does not look like an address still fails the whole list with 400. **Auth:** send your key as `x-api-key`, `Authorization: Bearer `, or `?apiKey=` (for WebSocket and EventSource, which cannot set headers). `/`, `/health` and `/openapi.yaml` need no key. **Rate limit:** requests per calendar minute, per key (keys of one account share the account's limit); 600 unless your plan sets another. Over it: 429 until the next minute. Opening a WebSocket or a stream is one request; its frames are free. **Live:** one WebSocket at `/ws` carries up to 200 channels (also at `wss://ws.raze.bot`); the same channels are available one per connection as Server-Sent Events at `/stream/{channel}`. Every channel sends a `snapshot` frame first (an `error` instead when `token` or `candles` cannot read its history), then changes. servers: - url: https://api.raze.bot description: Production security: - ApiKeyHeader: [] - Bearer: [] - ApiKeyQuery: [] tags: - name: catalog description: Health, chains and token search - name: tokens description: Token snapshot, trades, candles, holders, top traders, image - name: discovery description: Trending, screener and launchpad boards - name: wallets description: Wallet leaderboard, stats, holdings, PnL and swaps - name: prices description: Native coin prices and token prices - name: live description: WebSocket and Server-Sent Events paths: /tokens/{chain}/{address}/positions: get: tags: - tokens summary: Positions in a token description: > What each wallet did with this token over the last 365 days and holds now: buys and sells, amounts and USD in and out at the time of each swap, average buy price, realized profit, unrealized profit at the token's current `priceUsd` (the same price `/tokens` gives), first and last trade. A swap shows up within seconds. Fields are `null` when the source does not know the token, or a figure could not be measured. Figures are the wallet-stats source's; `/tokens/{chain}/{address}/traders` is another source's view of its top traders and can differ. Rows come in the order asked (a wallet asked twice comes twice). To follow a wallet live, read again on its `balance` frame of the [`wallet` channel](/streaming/channels#wallet), no sooner than 3 s after the previous read. operationId: getTokenPositions parameters: - $ref: '#/components/parameters/chain' - $ref: '#/components/parameters/address' - name: wallets in: query required: true description: 1 to 10 wallet addresses of the chain, comma separated schema: type: string responses: '200': description: One position per wallet asked content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Position' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/Upstream' components: parameters: chain: name: chain in: path required: true description: '`sol`, `eth`, `bsc`, `base` or `robinhood` (or an alias or network id)' schema: type: string example: sol address: name: address in: path required: true description: Token address (mint or contract) schema: type: string example: DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 schemas: Position: type: object description: >- One wallet's position in one token over the last 365 days. `null` is not measured, never 0. properties: chain: type: string token: type: string wallet: type: string balance: $ref: '#/components/schemas/num' description: Whole tokens held now valueUsd: $ref: '#/components/schemas/num' description: >- `balance` × `priceUsd`, only with a pool of at least $1,000 (as `/holdings`); 0 when none is held priceUsd: $ref: '#/components/schemas/num' description: The token's price as `/tokens` gives it buys: $ref: '#/components/schemas/int' sells: $ref: '#/components/schemas/int' boughtAmount: $ref: '#/components/schemas/num' description: Whole tokens soldAmount: $ref: '#/components/schemas/num' boughtUsd: $ref: '#/components/schemas/num' description: USD at the time of each swap soldUsd: $ref: '#/components/schemas/num' avgBuyPriceUsd: $ref: '#/components/schemas/num' description: '`boughtUsd` / `boughtAmount`, the plain average' realizedPnlUsd: $ref: '#/components/schemas/num' unrealizedPnlUsd: $ref: '#/components/schemas/num' description: >- The tokens bought and still held at `priceUsd`, less their cost (the cost consistent with `realizedPnlUsd`); 0 when none is held totalPnlUsd: $ref: '#/components/schemas/num' firstTradeAt: $ref: '#/components/schemas/int' lastTradeAt: $ref: '#/components/schemas/int' num: type: - number - 'null' int: type: - integer - 'null' Error: type: object properties: error: type: object properties: code: type: string enum: - bad_request - unauthorized - not_found - rate_limited - upstream_unavailable - server_busy message: type: string responses: BadRequest: description: A parameter is missing or wrong content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: bad_request message: 'unknown chain ''xyz'', use one of: sol, eth, bsc, base, robinhood' Unauthorized: description: Missing or unknown key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: missing or unknown API key (send it as x-api-key) RateLimited: description: >- Over the key's (or its account's) requests per minute; no rate-limit headers. Wait for the next minute content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited message: too many requests Upstream: description: > A source could not be read (`upstream_unavailable`). Send the same request again (same parameters, same cursor if any) after `Retry-After` seconds: 5 in general, 2 when a Solana trades, candles or wallet-trades page is out of reach for a moment. A market-cap chart of a token with no known supply answers this without `Retry-After` (ask with `unit=usd`). headers: Retry-After: schema: type: integer example: 5 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: upstream_unavailable message: could not load trades, try again securitySchemes: ApiKeyHeader: type: apiKey in: header name: x-api-key Bearer: type: http scheme: bearer ApiKeyQuery: type: apiKey in: query name: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.