Skip to main content
Clicker provides Realized PNL for onchain trading activity. This document explains what we provide, what you need to bring, and how our PNL calculations work.

​
What Clicker Provides

DataDescription
Cost BasisWhat you paid for your tokens, tracked per acquisition
HoldingsCurrent token balances per position
Realized PNLActual profit/loss from closed positions
Lot HistoryRecord of token acquisitions with cost basis
Sales HistoryRecord of dispositions with realized gains

​
How PNL Works

​
The Basic Flow

When you buy tokens and later sell them, Clicker tracks the cost basis and computes your realized gain or loss: 
+--------------------------------------------------------------+
|                     POSITION LIFECYCLE                       |
+--------------------------------------------------------------+
|                                                              |
|  BUY 100 tokens @ $1   --->   SELL ALL 100 tokens @ $5       |
|                                                              |
|  Cost: $100                   Proceeds: $500                 |
|                                                              |
|       |                            |                         |
|       v                            v                         |
|  +-----------+              +------------+                   |
|  |   OPEN    |  price moves |   CLOSED   |                   |
|  | POSITION  | -----------> |  POSITION  |                   |
|  +-----------+    $1 -> $5  +------------+                   |
|                                                              |
|  Realized PnL = Proceeds - Cost = $500 - $100 = $400         |
|                                                              |
|  Position closes when no tokens remain.                      |
|  Future acquisitions open a new position.                    |
|                                                              |
+--------------------------------------------------------------+

​
How Receives Are Handled

On-chain, tokens can arrive without a purchase - airdrops, bridge transfers, staking rewards, payments. Clicker assigns a cost basis at market price when received: 
+--------------------------------------------------------------+
|           API RESPONSE: POSITION WITH BUYS + RECEIVES        |
+--------------------------------------------------------------+
|                                                              |
|  BUY 500 tokens @ $8    = $4,000 spent                       |
|  RECV 500 tokens @ $10  = $5,000 market value at receive     |
|                                                              |
|  +-----------------------------------------------------+     |
|  |  "bought": 4000         <-- actual $ spent          |     |
|  |  "recv_basis": 5000     <-- cost from receives      |     |
|  |  "cost_basis": 9000     <-- used for PnL calc       |     |
|  +-----------------------------------------------------+     |
|                                                              |
|  Partners choose what to display:                            |
|    * "bought" alone for "total invested"                     |
|    * "cost_basis" for full accounting view                   |
|    * Both separately and let user toggle                     |
|                                                              |
+--------------------------------------------------------------+
FieldDefinition
boughtSum of actual dollars spent (buys only)
recv_basisMarket value of tokens at time of receive
cost_basisbought + recv_basis - used for PNL calculation

​
FIFO Lot Matching

When you sell tokens, Clicker uses FIFO (First In, First Out) to determine which tokens are sold first. Each acquisition creates a “lot” with its own cost basis: 
+--------------------------------------------------------------+
|              LOT QUEUE (FIFO - First In, First Out)          |
+--------------------------------------------------------------+
|                                                              |
|  +---------+   +---------+   +---------+                     |
|  | LOT 1   |   | LOT 2   |   | LOT 3   |    <-- newest       |
|  | 50 @ $2 |   | 30 @ $5 |   | 20 @ $8 |                     |
|  | (BUY)   |   | (RECV)  |   | (BUY)   |                     |
|  +---------+   +---------+   +---------+                     |
|       ^                                                      |
|       |                                                      |
|  oldest, sells first                                         |
|                                                              |
+--------------------------------------------------------------+

SELL 60 tokens @ $10:
  * 50 from LOT 1 (cost $2): PnL = 50 x ($10 - $2) = +$400
  * 10 from LOT 2 (cost $5): PnL = 10 x ($10 - $5) = +$50

Total Realized PnL: +$450
Remaining: 20 from LOT 2, 20 from LOT 3

​
What You Need to Bring: Unrealized PNL

Clicker does not provide realtime token prices. We focus on the hard accounting problem - tracking cost basis and computing realized gains - while you retain control over pricing. For Unrealized PNL (paper gains on current holdings), use: 
Unrealized PNL = (Holdings × Your Realtime Price) − Cost Basis
InputSource
HoldingsClicker API
Cost BasisClicker API
Realtime PriceYour pricing feed (Codex, CoinGecko, DEX, etc.)
This separation lets you choose your pricing oracle while we handle the accounting complexity.

​
Why PNL Is Harder Than It Looks

Building accurate PNL for onchain trading involves solving several interconnected problems:

​
Swap Detection

A blockchain transaction is just a list of token transfers. Determining whether those transfers represent a buy, sell, swap, airdrop, bridge, or something else requires parsing balance changes, identifying contract patterns (DEX routers, bridges), handling multi-hop swaps, and distinguishing intentional trades from fees, MEV, and dust.

​
Cost Basis Tracking

Each acquisition creates a lot record: (token, amount, unit_price, timestamp, type). Partial sales consume lots in FIFO order, splitting lots when necessary. Receives are priced at market rate via Codex at transaction time.

​
Position Lifecycle

Position opens on first acquisition, closes when balance reaches zero (below dust threshold of ~$0.01). Re-acquiring after full sale opens a new position with fresh lots.

​
Edge Cases

Failed transactions with partial state changes, LP token mints/burns, and cross-chain trades.

​
What We Handle

Clicker solves these problems so you don’t have to:
  • Swap derivation from raw transaction data
  • Cost basis tracking across acquisitions
  • FIFO accounting for sales
  • Position lifecycle management
  • Cross-chain awareness for common bridges
  • Historical pricing at transaction time (via Codex)
You get clean, computed PNL data. We handle the complexity.

​
Summary

ConcernWho Handles It
Cost basis trackingClicker
Realized PNLClicker
Position accountingClicker
Swap detectionClicker
Realtime pricingYou
Unrealized PNLYou (using our data)