agentutility(7)$ man wallet-pnl
/wallet-pnl
PRICE / CALL
$0.05
USDC · base mainnet · scheme: exact
METHOD
POST
CLUSTER
edgemarketCATEGORY
uncategorized
STATUS
● live
NAME
wallet-pnl — computes wallet token p&l with fifo cost basis for any (wallet, erc-20, chain) triple
SYNOPSIS
POST https://x402.agentutility.ai/wallet-pnl
Content-Type: application/json
X-PAYMENT: <signed-transferWithAuthorization>
{ ... }↳ first call →
402 Payment Required. Sign USDCtransferWithAuthorization, retry with theX-PAYMENT header.DESCRIPTION
Computes wallet token P&L with FIFO cost basis for any (wallet, ERC-20, chain) triple. Pulls all transfers from Etherscan v2, prices each one at the historical USD spot via CoinGecko, runs FIFO accounting, and reports cost basis, realized gain, unrealized gain, current balance, and tx count. Capped at the most recent 500 transfers. Use it as a realized + unrealized profit calculator or EVM portfolio analytics tool.
INPUT — request schema
| property | type | description | req? |
|---|---|---|---|
| wallet | string | 0x-prefixed 20-byte wallet address. | required |
| token_address | string | 0x-prefixed 20-byte ERC-20 contract. | required |
| chain | string | EVM chain. Default 'ethereum'. enum: base · ethereum · polygon · arbitrum · optimism | optional |
OUTPUT — response shape
| field | type | description |
|---|---|---|
| wallet | string | EVM wallet address whose token P&L was computed. |
| token | string | ERC-20 contract address of the token analyzed. |
| chain | string | EVM chain the wallet and token live on (e.g. ethereum, base, polygon). |
| symbol | string | Ticker symbol of the ERC-20 token (e.g. USDC, WETH). |
| decimals | string | Number of decimal places the ERC-20 contract uses to format balances. |
| tx_count | string | Total transfer count for this wallet/token pair included in the FIFO calculation. |
| transfers_in | string | Count of inbound transfers credited to the wallet's FIFO inventory. |
| transfers_out | string | Count of outbound transfers consumed against FIFO inventory to realize gains. |
| current_balance | string | Wallet's current token balance after applying all in/out transfers, in human units. |
| current_price_usd | string | Latest USD spot price per token from CoinGecko at query time. |
| cost_basis_usd | string | FIFO cost basis in USD for the wallet's remaining token balance. |
| realized_pnl_usd | string | USD profit/loss already locked in by outbound transfers under FIFO accounting. |
| unrealized_pnl_usd | string | USD profit/loss on the current balance at current price vs remaining cost basis. |
| total_pnl_usd | string | Sum of realized and unrealized USD P&L for this wallet/token/chain triple. |
| capped_at | string | Max transfer count the calculation considered (500 if the wallet exceeded the cap). |
| coingecko_id | string | CoinGecko asset ID used to fetch historical and current USD prices for the token. |
| source | string | Origin of the underlying transfer + price data (e.g. etherscan_v2+coingecko). |
EXAMPLES — two ways to call
EXAMPLE 1 · curl
curl -X POST https://x402.agentutility.ai/wallet-pnl \
-H 'Content-Type: application/json' \
-d '{ }'first response =
402 Payment Required with payment requirements; sign + retry with X-PAYMENT.EXAMPLE 2 · mcp
# Install the MCP package for this endpoint's cluster npx -y @agentutility/mcp-<cluster> # Required: EVM private key with USDC on Base export X402_PRIVATE_KEY=0x... # Then call the wallet-pnl tool from your MCP-aware agent.
MCP server handles payment automatically — your coding agent just calls the tool by name.
METADATA
- tags
- edge-marketwallet-analyticsportfolio-trackingcost-basisfifo-accountingrealized-pnlerc-20wallet-pnl
- methods
- POST
- cluster
- edgemarket
- price
- $0.05 USDC per call
ADJACENT — other endpoints in edgemarket
| endpoint | description | price |
|---|---|---|
| honeypot-check | Honeypot.is buy/sell simulation for any Base or Ethereum ERC-20. | $0.05 |
| token-honeypot | Detects whether an ERC-20 token is a honeypot by simulating a buy + sell via honeypot.is. | $0.05 |
| token-honeypot-api | Checks whether a token is a honeypot, testing sellability, buy tax, sell tax, proxy risk, owner risk, and token-trading warnings. | $0.05 |
| token-honeypot-check | Checks whether an ERC-20 token is a honeypot by simulating buy and sell behavior through honeypot.is. | $0.05 |
| crypto-tx-explainer | Ethereum/Base/Arbitrum/Optimism/Polygon transaction explainer. | $0.04 |
| bridge-rates | Compares cross-chain bridge quotes to find the cheapest route between chains, powered by LiFi. | $0.03 |
| dao-proposal-monitor | Monitors DAO governance proposals on Snapshot.org for any space. | $0.03 |
| ens-resolve | Resolves ENS names in both directions: forward (vitalik.eth to address) and reverse (address to primary ENS). | $0.03 |
SEE ALSO