Skip to main content
GET
/
user
/
pnl
curl "https://api.bison.markets/user/pnl?userId=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"

{
  "totalDeposits": "500000000",
  "totalWithdrawals": "100000000",
  "realizedPnl": "25000000",
  "unrealizedPnl": "5000000",
  "netPnl": "30000000",
  "totalFeesPaid": "150000"
}

​
Overview

Returns a comprehensive PNL (Profit and Loss) summary for a user, including:
  • Realized PNL - Profit/loss from completed trades and settlements
  • Unrealized PNL - Estimated profit/loss on open positions
  • Net PNL - Combined realized and unrealized PNL
  • Total Fees - All trading fees paid
  • Time Series - Optional PNL over time
To avoid ambiguity, we denote the smallest possible multiple of USDC (0.000001 USDC) as one uusdc, which stands for µUSDC (micro-USDC), and denote the smallest possible multiple of a contract (0.01 contract) as one ccontract (centicontract).User-facing USDC balances are specified as fixed-point strings (e.g. "1.2625" for USDC). Contract quantities in the API and SDK are specified as integer ccontracts strings (e.g. "1050" for 10.50 contracts at precision 2).

​
PNL Calculation

Realized PNL is calculated as: 
Realized PNL = Sell Revenue + Settlement Payouts - Buy Costs - Fees
Unrealized PNL estimates the value of open positions based on their cost basis compared to an estimated current value.
​
userId
string
required
User’s Ethereum wallet address (e.g., 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266)
​
marketId
string
Filter PNL calculation to a specific market. When set, deposits and withdrawals are excluded from the calculation.
​
startTime
number
Start timestamp in milliseconds. Only includes transactions after this time.
​
endTime
number
End timestamp in milliseconds. Only includes transactions before this time.
​
granularity
string
default:"all"
Time-series granularity for the timeSeries field:
  • all - No time series returned (default)
  • hour - Hourly PNL snapshots
  • day - Daily PNL snapshots

​
Response

​
totalDeposits
string
required
Total USDC deposited in µUSDC (integer string). Excluded when filtering by marketId.
​
totalWithdrawals
string
required
Total USDC withdrawn (claimed) in µUSDC (integer string). Excluded when filtering by marketId.
​
realizedPnl
string
required
Realized profit/loss in µUSDC (integer string). Positive = profit, negative = loss.
​
unrealizedPnl
string
required
Estimated unrealized profit/loss in µUSDC based on open positions (integer string).
​
netPnl
string
required
Total PNL (realized + unrealized) in µUSDC (integer string).
​
totalFeesPaid
string
required
Total trading fees paid in µUSDC (integer string).
​
timeSeries
array
Cumulative PNL over time. Only returned when granularity is hour or day.
curl "https://api.bison.markets/user/pnl?userId=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"

{
  "totalDeposits": "500000000",
  "totalWithdrawals": "100000000",
  "realizedPnl": "25000000",
  "unrealizedPnl": "5000000",
  "netPnl": "30000000",
  "totalFeesPaid": "150000"
}

​
Use Cases

​
Portfolio Dashboard

Display overall trading performance: 
const pnl = await fetch('/user/pnl?userId=0x...').then(r => r.json());

console.log(`Net P&L: $${Number(pnl.netPnl) / 1_000_000}`);
console.log(`Fees Paid: $${Number(pnl.totalFeesPaid) / 1_000_000}`);

​
Performance Chart

Build a PNL chart over time: 
const pnl = await fetch('/user/pnl?userId=0x...&granularity=day').then(r => r.json());

// pnl.timeSeries contains daily cumulative PNL points
const chartData = pnl.timeSeries.map(point => ({
  date: new Date(point.timestamp),
  pnl: Number(point.cumulativePnl) / 1_000_000
}));

​
Market-Specific Analysis

Analyze performance on a specific market: 
const marketPnl = await fetch(
  '/user/pnl?userId=0x...&marketId=KXFEDDECISION-26JAN-T425'
).then(r => r.json());

console.log(`Market P&L: $${Number(marketPnl.realizedPnl) / 1_000_000}`);