Skip to main content
GET
/
v1
/
predexon
/
wallet
/
pnl
/
{wallet_address}
curl -s "https://api.predexon.com/v1/predexon/wallet/pnl/0xabc123def456abc123def456abc123def456abc1?granularity=daily&start_time=1732370400&end_time=1735048800" \
  -H "x-api-key: YOUR_API_KEY"

{
  "granularity": "daily",
  "start_time": 1732975200,
  "end_time": 1735653600,
  "wallet_address": "0xabc123def456abc123def456abc123def456abc1",
  "pnl_over_time": [
    {
      "timestamp": 1732975200,
      "realized_pnl": 125.50,
      "cumulative_pnl": 125.50,
      "num_trades": 5
    },
    {
      "timestamp": 1733061600,
      "realized_pnl": -45.20,
      "cumulative_pnl": 80.30,
      "num_trades": 3
    },
    {
      "timestamp": 1733148000,
      "realized_pnl": 220.75,
      "cumulative_pnl": 301.05,
      "num_trades": 8
    }
  ]
}

​
Overview

Retrieve realized profit and loss (PnL) data for a specific wallet address. This endpoint tracks realized gains and losses from completed trades (sells or redeems) aggregated by your specified time granularity.
Realized PnL Only: This endpoint tracks realized gains/losses from executed trades only. Unrealized PnL from current open positions is not included. For a complete portfolio view, you should also track unrealized PnL separately.

​
Use Cases

  • Portfolio Performance Analysis: Track how your trading strategy has performed over time
  • Tax Reporting: Calculate realized gains and losses for tax year planning and reporting
  • Performance Tracking: Analyze PnL trends across different time periods (daily, weekly, monthly, yearly)
  • Risk Assessment: Understand cumulative performance and volatility patterns

​
Endpoint

​
Authentication

All requests require an API key passed in the x-api-key header: 
x-api-key: YOUR_API_KEY
You can find your API key in your account settings. Keep it secure and never share it publicly.

​
Path Parameters

​
wallet_address
string
required
The Ethereum wallet address to retrieve PnL data for. Must be a valid Ethereum address (0x-prefixed, 42 characters).Examples:
  • 0x1234567890123456789012345678901234567890
  • 0xaAbBcCddEeFfAaBbCcDdEeFfAaBbCcDdEeFfAaBb

​
Query Parameters

​
granularity
enum
required
Time granularity for aggregating PnL data.Allowed values:
  • daily - Daily PnL aggregation
  • weekly - Weekly PnL aggregation (Monday-Sunday)
  • monthly - Monthly PnL aggregation (calendar month)
  • yearly - Yearly PnL aggregation (calendar year)
​
start_time
integer
Unix timestamp (seconds) for the start of the query period.
  • Minimum value: 0
  • Default: First trade timestamp for the wallet
  • Must be less than end_time
Note: If not provided, data starts from the wallet’s first recorded trade.
​
end_time
integer
Unix timestamp (seconds) for the end of the query period.
  • Minimum value: 0
  • Default: Current Unix timestamp
  • Must be greater than start_time
Note: If not provided, data ends at the current time.

​
Response

The endpoint returns a time-series PnL structure with realized gains/losses aggregated by the specified granularity.
​
granularity
string
The time granularity used for aggregation (daily, weekly, monthly, or yearly).
​
start_time
integer
Unix timestamp (seconds) for the start of the returned data period.
​
end_time
integer
Unix timestamp (seconds) for the end of the returned data period.
​
wallet_address
string
The Ethereum wallet address for which PnL was calculated.
​
pnl_over_time
array
Array of PnL data points, one per time period (day, week, month, or year).

​
Response Schema

{
  "granularity": "daily",
  "start_time": 1732975200,
  "end_time": 1735653600,
  "wallet_address": "0xabc123def456abc123def456abc123def456abc1",
  "pnl_over_time": [
    {
      "timestamp": 1732975200,
      "realized_pnl": 125.50,
      "cumulative_pnl": 125.50,
      "num_trades": 5
    },
    {
      "timestamp": 1733061600,
      "realized_pnl": -45.20,
      "cumulative_pnl": 80.30,
      "num_trades": 3
    },
    {
      "timestamp": 1733148000,
      "realized_pnl": 220.75,
      "cumulative_pnl": 301.05,
      "num_trades": 8
    }
  ]
}

​
Error Responses

​
status
integer
HTTP status code
​
detail
string
Error message describing what went wrong

​
Common Errors

StatusErrorResolution
400Invalid wallet address formatEnsure the wallet address is a valid 42-character Ethereum address starting with 0x
400start_time must be less than end_timeVerify that your start_time timestamp is earlier than end_time
401Unauthorized - Invalid API keyCheck that your x-api-key header is correct
404Wallet not foundThe wallet address has no recorded trading history
429Rate limit exceededToo many requests. Please wait before retrying
500Internal server errorTemporary issue. Please try again or contact support

​
Examples

curl -s "https://api.predexon.com/v1/predexon/wallet/pnl/0xabc123def456abc123def456abc123def456abc1?granularity=daily&start_time=1732370400&end_time=1735048800" \
  -H "x-api-key: YOUR_API_KEY"

{
  "granularity": "daily",
  "start_time": 1732975200,
  "end_time": 1735653600,
  "wallet_address": "0xabc123def456abc123def456abc123def456abc1",
  "pnl_over_time": [
    {
      "timestamp": 1732975200,
      "realized_pnl": 125.50,
      "cumulative_pnl": 125.50,
      "num_trades": 5
    },
    {
      "timestamp": 1733061600,
      "realized_pnl": -45.20,
      "cumulative_pnl": 80.30,
      "num_trades": 3
    },
    {
      "timestamp": 1733148000,
      "realized_pnl": 220.75,
      "cumulative_pnl": 301.05,
      "num_trades": 8
    }
  ]
}

​
Data Interpretation

​
Understanding the Response Fields

realized_pnl: The profit or loss during this specific period only.
  • Positive values indicate profit
  • Negative values indicate losses
  • Calculated from actual executed trades (sells/redeems)
cumulative_pnl: Running total of all realized PnL from start_time to current period.
  • Shows total accumulated gains/losses
  • Useful for understanding overall portfolio performance
  • Always increases or decreases monotonically from start to end
num_trades: Count of trades that generated PnL during this period.
  • Helps identify periods of high vs. low trading activity
  • A period with 0 trades will have 0 realized_pnl

​
Example Analysis

{
  "granularity": "daily",
  "pnl_over_time": [
    {
      "timestamp": 1732975200,
      "realized_pnl": 125.50,      // Day 1: Made $125.50
      "cumulative_pnl": 125.50,    // Total so far: $125.50
      "num_trades": 5              // From 5 trades
    },
    {
      "timestamp": 1733061600,
      "realized_pnl": -45.20,       // Day 2: Lost $45.20
      "cumulative_pnl": 80.30,      // Total so far: $80.30
      "num_trades": 3               // From 3 trades
    }
  ]
}

​
Validation Rules

  • start_time must be less than end_time
  • start_time and end_time must be non-negative integers (Unix timestamps)
  • wallet_address must be a valid Ethereum address format (0x-prefixed, 42 characters)
  • granularity must be one of: daily, weekly, monthly, yearly
  • If no parameters are provided beyond wallet_address and granularity, the endpoint will return all available historical data

​
Rate Limiting

  • Standard rate limit: 100 requests per minute
  • Burst limit: 10 requests per second
  • Rate limit headers are included in responses:
    • X-RateLimit-Limit: Maximum requests allowed
    • X-RateLimit-Remaining: Requests remaining in current window
    • X-RateLimit-Reset: Unix timestamp when limit resets
For high-volume queries, consider caching results locally and only fetching new data periodically.

​
Best Practices

  1. Specify Time Ranges: Rather than querying entire history, specify meaningful start_time and end_time values for better performance.
  2. Choose Appropriate Granularity:
    • Use daily for recent trading activity analysis
    • Use weekly for short-term trends (weeks to months)
    • Use monthly for medium-term analysis (quarter to year)
    • Use yearly for long-term historical analysis
  3. Handle Empty Periods: A period with num_trades: 0 and realized_pnl: 0 means no trades occurred during that period.
  4. Tax Reporting: For tax purposes, group by yearly or monthly granularity and track realized_pnl carefully, as this represents taxable gains/losses.
  5. Error Handling: Always check HTTP status codes and handle 400/401/404 errors gracefully: 
    if response.status_code == 404:
    print("Wallet not found - no trading history")
elif response.status_code == 400:
    print("Invalid parameters - check wallet address and timestamps")

​
FAQ

  • Realized PnL: Gains/losses from completed trades (sells, redeems). This is what this endpoint returns.
  • Unrealized PnL: Gains/losses from positions you still hold. These are potential profits that could change.
This endpoint only tracks realized PnL because it’s concrete and locked in.
No, the finest granularity available is daily. For intra-day analysis, you can query multiple daily periods and analyze the pattern.
All timestamps are in Unix format (seconds since January 1, 1970 UTC). The period start times are always at 00:00:00 UTC for daily periods, and Monday 00:00:00 UTC for weekly periods.
You can query any period from the wallet’s first recorded trade up to the current time. If you provide no start_time, it defaults to the first trade.
This could mean:
  • The wallet has never made a sell or redeem transaction
  • The wallet only has open/unrealized positions
  • The time range you specified has no trades
Check the num_trades field to verify if trades occurred during the period.
Yes, this endpoint provides historical realized PnL data which can inform strategy analysis and backtesting analysis, though it represents past performance only.