Vike Data API

Wallet Positions

wallet_positions

Read-onlyIdempotent

A wallet's per-token positions on one chain with real profit and loss. Per token: token_address, symbol, name, bought_qty and bought_usd, sold_qty and sold_usd, avg_buy_price and avg_sell_price (USD per token), realized_pnl_usd, balance (read from the chain at request time), price_usd (latest daily price), value_usd and unrealized_pnl_usd = balance x (price_usd - avg_buy_price), null when either is unknown. Bought and sold are the wallet's priced inbound and outbound transfers of the token (a swap, a move between its own wallets and an exchange deposit all count); a transfer with no USD price (a mint, a pre-listing airdrop) is neither. Realized PnL is average cost: only units that were bought are realized, the chain's coin and its wrapped token (WETH, WBNB, WHYPE) are one position under the zero address, and Ethereum stablecoins and disabled tokens are left out. totals cover EVERY token the wallet traded, not only the rows returned: realized_pnl_usd, unrealized_pnl_usd (over the tokens where it is known), tokens_traded, tokens_profitable and as_of, when the wallet's lifetime PnL in the wallet rankings was last recomputed (updated nightly at 04:00 UTC); the positions count trades up to the latest priced transfers, so the two differ only when the wallet traded since. USD in plain dollars. found is false for a wallet with no priced trade. Use when the user asks 'what did this wallet make on each token' / 'is it in profit' / 'what is it holding and at what cost'; wallet_pnl_history is a daily net-flow series, not this.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "address": "<address>"
    },
    "name": "wallet_positions"
  }
}

Input Schema

Name	Required	Description	Default
`sort`	No	Rank positions by realized PnL, unrealized PnL or current value (default realized). Unknown values sort last	realized
`chain`	No	Chain (default ethereum)	ethereum
`limit`	No	Positions returned (default 20, max 100); totals always cover every token
`order`	No	desc = biggest first (default), asc = biggest losses first	desc
`address`	Yes	Wallet address (0x-prefixed)

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 3, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the read-only annotations, the description discloses key behavioral details: what counts as bought/sold, how realized PnL is calculated, how wrapped native tokens are merged, which tokens are excluded, and what `found` means. It also explains that totals cover every traded token while rows are limited, and notes the nightly 04:00 UTC recomputation behind `as_of`.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded, and nearly every sentence adds necessary financial or filtering semantics. The single dense paragraph is information-rich but could be slightly easier to scan with structure, so it is not perfect.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema, the description thoroughly explains the returned per-token fields, totals, calculation rules, and the `found` flag. It gives an agent enough context to call the tool correctly and interpret its response without needing additional documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already documents `sort`, `chain`, `limit`, `order`, and `address` with defaults and enum behavior. The description reinforces that totals cover every token regardless of `limit`, but it does not add much parameter-specific meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and scope: a wallet's per-token positions on one chain, including real profit and loss. It clearly distinguishes itself from wallet_pnl_history by calling that tool a daily net-flow series rather than per-token positions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit user-question triggers such as 'what did this wallet make on each token' and 'is it in profit'. It also names the alternative tool, wallet_pnl_history, and explains why it is not the right choice for this question.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Vike Data API tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.