Skip to main content
GET
Copy PnL
Calculate a wallet’s gross trading cash flow and the cash flow of a simulated copier using Polynode’s indexed fills and settlement events. This replaces the deprecated V2 on-demand endpoint.

Request

The cap counts fills, not positions, tokens, transactions, or distinct orders. The calculation selects the wallet’s own signed-order fill records, including its taker-order execution record. It avoids counting that wallet again as the counterparty to other matched orders. This attribution is different from requesting both address roles on the raw trades endpoint. There is no default date window. With history=recent, active wallets can reach 50,000 fills quickly; quieter wallets can cover years. Date filters apply before the fill cap, including to settlement events. A wallet with fewer matching fills returns all matching indexed fills. coverage.history_truncated tells you whether older fills inside the requested date window were excluded by the fill selection.

History modes

  • recent: return up to max_trades recent fills. This preserves the original V3 default.
  • auto: first complete the recent calculation, then spend up to two additional seconds extending toward all matching history, within the overall calculation deadline. Return full history if it completes; otherwise return the original completed recent calculation with an explicit fallback reason.
  • full: require all matching indexed history. If the work or time limit is reached, return an error instead of a recent-window fallback.
Full-history work is bounded at 500,000 fills and 100,000 settlement events per wallet. Both auto and full can return more than 50,000 fills. max_trades remains limited to 50,000 and controls the initial recent calculation. A successful full result contains all matching history, never the first 500,000 fills of a larger history. For example, request a complete historical month with ?history=full&from=2026-08-01&to=2026-09-01, or use ?history=auto&period=90d to allow an explicit recent-window fallback. Read coverage.requested_history, served_history (full or recent), and fallback_reason on every result. served_history=full means the requested date window is complete; lifetime_history_included is true only when no date filters or fill truncation restrict the indexed history. Automatic fallback reasons are query_timeout, query_work_limit, activity_limit_exceeded, or history_limit_exceeded. If the initial recent calculation fails, there is no valid fallback and the request returns an error.

Calculation

  • Buy: the copier pays min(price × 1.02, 1.00) × shares.
  • Sell: the copier receives price × 0.98 × shares.
  • Splits consume collateral; merges and redemptions release collateral. Neg-risk conversions include released collateral according to their selected outcomes. These settlement flows receive no simulated slippage.
The 2% assumption is relative to each execution price. It is a fixed screening model, not a measured execution cost or a forecast. When the absolute gross cash flow is below 1 USDC, both the percentage and toxic_for_copying are null.
pnl_definition is cashflow. Fees are excluded, opening inventory is not valued, and open positions are not marked to market. Sales or redemptions of inventory acquired before the selected window can therefore make this differ substantially from realized or total portfolio PnL. Deposits, withdrawals, and token transfers are outside this calculation. It covers spot order fills, not combo or perpetual trading.
If older matching fills are excluded, settlement inclusion begins at the exact block and log of the first included fill, inclusive. Otherwise, all indexed settlement history within the requested dates is eligible, including events before the first fill. A wallet with settlement activity and no fills can still return a cash-flow result. Explicit timestamps are checked exactly; the database snapshot bounds which events are visible.

Realized-PnL context

realized_pnl_context provides the wallet’s stored lifetime realized profit and position counts alongside the cash-flow simulation. Its total_realized_pnl_usdc is actual realized profit from the wallet summary; it is not the copier’s simulated realized profit and is not used in the slippage or copying flag formulas. This context always has scope: "lifetime_wallet" and date_filters_applied: false. It is not rewound by from or to and is not a realized-profit result for a historical backtest window. Read updated_at, updated_block, and refresh_age_seconds to see the summary’s last update. latest_indexed_fill_block supports the freshness indicator: behind_indexed_fills, no_newer_indexed_fills, unknown, or unavailable. No newer fills does not prove all settlement or valuation inputs are current. If no summary is available, available is false and its profit/count/update fields are null, rather than zero. position_count and open_positions describe the stored lifetime summary. They do not reproduce V2’s count of positions with nonzero realized PnL.

Response

The following is an illustrative two-fill calculation: a buy costing 5 USDC followed by a sale returning 8 USDC, with no settlement flows.
Money and percentages are decimal strings with six fractional digits. Event timestamps are Unix seconds. snapshot_at is a UTC timestamp. For a truncated history, window_start contains type: "inclusive_trade_cursor", block_number and log_index as strings, and timestamp in Unix seconds. A complete window with a start date uses type: "inclusive_timestamp" and timestamp. window_end is either an exclusive_timestamp or a database_snapshot. applied_filters reports the resolved date bounds; without explicit dates, its to records the snapshot time in whole seconds. An empty wallet has zero cash-flow amounts and null first/last event timestamps. Results may be cached for 30 seconds after calculation, separately for each wallet and set of options. cache.status is miss, hit, or coalesced (shared in-progress work). cache.age_ms measures time since the calculation’s snapshot; data.query_ms describes that calculation, including any attempted history expansion, while elapsed_ms describes the current request. Each wallet has its own snapshot, including in a batch. Relative periods are anchored to that calculation; supply explicit from and to to fix the same date window across wallets.

Access and errors

Available on paid V3 plans under the account’s normal REST limits and monthly usage policy. The V2-specific one-request-per-five-seconds limit does not apply. Each HTTP request counts as one API request, including a batch. Cache hits still count as requests. Database capacity is bounded; account request limits are not a guarantee of uncached calculation throughput. Authentication, plan access, monthly usage, and account rate-limit failures use the normal V3 edge responses. Do not treat an error as zero PnL.

Migrating from V2

Use GET /v3/wallets/{address}/copy-pnl or V3 Copy PnL Batch. Read the summary from data; batch input uses wallets instead of addresses. period, from, and to are supported. V2 defaulted to 30 days; send period=30d explicitly to request that window in V3. Use history=full when the whole requested window is required, or auto when an explicit recent-window fallback is acceptable. Read actual lifetime realized PnL from realized_pnl_context.total_realized_pnl_usdc, with the scope and freshness limitations above. This does not restore V2’s window-specific weighted-average position metrics. include_trades, individual trade arrays, weighted entry/holding metrics, and V2’s BYOB tracked-wallet pool, snapshot, and leaderboard remain outside these endpoints.

Authorizations

x-api-key
string
header
required

Path Parameters

address
string
required
Pattern: ^0x[0-9a-fA-F]{40}$

Query Parameters

max_trades
integer
default:50000

Recent/fallback fill cap per wallet; initial scan size in full mode. Auto/full may return more fills, up to the 500000-fill work limit.

Required range: 1 <= x <= 50000
history
enum<string>
default:recent

recent keeps the cap; auto attempts full history with an explicit recent fallback; full requires complete matching history or returns an error.

Available options:
recent,
auto,
full
period
enum<string>

Optional window ending at to or the calculation snapshot. No default period. Explicit from overrides period.

Available options:
7d,
14d,
30d,
60d,
90d,
180d
from

Inclusive start: Unix seconds or YYYY-MM-DD at UTC midnight. Applies to fills and settlement events, not lifetime realized-PnL context.

Required range: 0 <= x <= 253402300799
to

Exclusive end: Unix seconds or YYYY-MM-DD at UTC midnight. Defaults to the calculation snapshot.

Required range: 0 <= x <= 253402300799

Response

Complete bounded wallet calculation

data
object
required
cache
object
required
elapsed_ms
integer
required