Documentation Index
Fetch the complete documentation index at: https://docs.clicker.xyz/llms.txt
Use this file to discover all available pages before exploring further.
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
| Data | Description |
|---|
| Cost Basis | What you paid for your tokens, tracked per acquisition |
| Holdings | Current token balances per position |
| Realized PNL | Actual profit/loss from closed positions |
| Lot History | Record of token acquisitions with cost basis |
| Sales History | Record 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 |
| |
+--------------------------------------------------------------+
| Field | Definition |
|---|
| bought | Sum of actual dollars spent (buys only) |
| recv_basis | Market value of tokens at time of receive |
| cost_basis | bought + 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
Position-Based PnL (Not Token-Based)
Clicker uses position-based PnL tracking, which is the standard approach used by leading trading apps like Axiom and fomo. This differs from token-based systems that aggregate all activity on a token into a single view.
How It Works
When you buy a token, Clicker opens a position. When you sell all of it, that position closes. If you re-enter that same token later, a new position opens with its own separate PnL:
+--------------------------------------------------------------+
| POSITION-BASED TRACKING |
+--------------------------------------------------------------+
| |
| Jan 1: Buy $XYZ ---> Position A opens |
| Feb 2: Sell all ---> Position A closes (+$3,100) |
| |
| Jun 15: Buy $XYZ again ---> Position B opens (fresh start) |
| Jul 20: Sell all ---> Position B closes (-$200) |
| |
+--------------------------------------------------------------+
| |
| Position A PnL: +$3,100 (closed Feb 2) |
| Position B PnL: -$200 (closed Jul 20) |
| |
| These are tracked SEPARATELY - Position B starts fresh. |
| |
+--------------------------------------------------------------+
Why Position-Based Matters
With position-based tracking, each position stands on its own. This makes it easier to:
- Reason about your trading history - See exactly how each entry into a token performed
- Evaluate current positions clearly - Your new entry’s PnL isn’t clouded by gains or losses from previous trades in the same token
Token-Based Systems Are Different
Some portfolio trackers use token-based PnL, which aggregates all activity on a token into one combined view. In the example above, a token-based system would show:
$XYZ total PnL: +$2,900 (combined from both entries)
Trade Types: Buys, Sells, and Swaps
Clicker categorizes every trade based on the tokens involved. This determines how we price each side of the trade.
Quote Tokens
Quote tokens are the “base currencies” of crypto trading:
- Native assets: ETH, SOL, and other chain-native tokens
- Stablecoins: USDC, USDT, DAI, and other standard stablecoins
These are the tokens traders typically use to enter and exit positions.
How We Categorize Trades
| Trade Type | Definition | Example |
|---|
| Buy | Spending a quote token to acquire a non-quote token | ETH → PEPE |
| Sell | Selling a non-quote token back into a quote token | PEPE → USDC |
| Swap | Trading one non-quote token for another | PEPE → WIF |
How We Price Trades
Every trade has two sides: the token you send (sold) and the token you receive (bought). Clicker prices both sides independently at the block timestamp, then uses the appropriate side to determine trade value:
+--------------------------------------------------------------+
| TRADE PRICING BY TYPE |
+--------------------------------------------------------------+
| |
| BUY (ETH -> PEPE) |
| +---------------------------------------------------------+ |
| | Sold: 0.5 ETH @ $3,000 = $1,500 | |
| | Bought: 1,000,000 PEPE | |
| | | |
| | Trade Value = $1,500 (from sold asset - the ETH) | |
| | Cost Basis = $0.0015 per PEPE | |
| +---------------------------------------------------------+ |
| |
| SELL (PEPE -> USDC) |
| +---------------------------------------------------------+ |
| | Sold: 1,000,000 PEPE | |
| | Bought: 2,000 USDC @ $1 = $2,000 | |
| | | |
| | Trade Value = $2,000 (from bought asset - the USDC) | |
| | Realized PnL = $2,000 - $1,500 cost basis = +$500 | |
| +---------------------------------------------------------+ |
| |
| SWAP (PEPE -> WIF) |
| +---------------------------------------------------------+ |
| | Sold: 500,000 PEPE @ $0.002 = $1,000 | |
| | Bought: 100 WIF @ $9.75 = $975 | |
| | | |
| | A swap updates TWO positions: | |
| | | |
| | PEPE position (sell side): | |
| | Sale value = $975 (from bought WIF) | |
| | Realized PnL calculated against PEPE cost basis | |
| | | |
| | WIF position (buy side): | |
| | Cost basis = $1,000 (from sold PEPE) | |
| | New lot added to WIF position | |
| | | |
| | Prices often differ on either side of a swap. | |
| +---------------------------------------------------------+ |
| |
+--------------------------------------------------------------+
Why We Price This Way
- Buys: The quote token (ETH, USDC) has reliable pricing. We use it to determine what you paid for the new token.
- Sells: The quote token you receive has reliable pricing. We use it to determine your proceeds.
- Swaps: Neither token is a quote token, so we price both independently. The sold token’s value becomes the cost basis for what you bought, and the bought token’s value determines the sale proceeds for what you sold. These values may differ slightly due to liquidity differences.
This approach ensures consistent PnL tracking even when trading between volatile assets.
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.
You combine our data with your live prices to compute unrealized PnL, current position value, and percent change. See the Position Calculations guide for the full formulas covering both spot and perp positions.
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 remaining value drops below the dust threshold of $1. 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
| Concern | Who Handles It |
|---|
| Cost basis tracking | Clicker |
| Realized PNL | Clicker |
| Position accounting | Clicker |
| Swap detection | Clicker |
| Realtime pricing | You |
| Unrealized PNL | You (using our data) — see Position Calculations |
