> For the complete documentation index, see [llms.txt](https://falcon-bot.gitbook.io/falcon-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://falcon-bot.gitbook.io/falcon-api/market-intelligence/falcon-wallet-360.md).
# Falcon Wallet 360
### Request Body (JSON)
```json
{
"agent_id": 581,
"params": {
"proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
"window_days": "3"
},
"pagination": {
"limit": 100,
"offset": 0
},
"formatter_config": {
"format_type": "raw"
}
}
```
### Available Filters
| Parameter | Type | Description | Example |
| -------------- | ------ | ------------------------------------------------------- | --------------- |
| `proxy_wallet` | String | Wallet address to analyze | `"0xabc123..."` |
| `window_days` | String | Metric calculation window. Options: `1`, `3`, `7`, `15` | `"1"` |
Example Request (cURL)
```bash
curl --location 'https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"agent_id": 581,
"params": {
"proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
"window_days": "3"
},
"pagination": {
"limit": 100,
"offset": 0
},
"formatter_config": {
"format_type": "raw"
}
}'
```
***
### Response Fields
| `date` | String (ISO 8601) | Aggregation date |
| ------------------------------- | ----------------- | ----------------------------------------------------------------------- |
| `proxy_wallet` | String | Wallet address |
| `calculation_window_days` | Integer | Number of days used for metric calculation |
| `date_range_start` | String (ISO 8601) | Start date of calculation window |
| `date_range_end` | String (ISO 8601) | End date of calculation window |
| `total_trades` | Integer | Total number of trades |
| `winning_trades` | Integer | Number of profitable trades |
| `losing_trades` | Integer | Number of losing trades |
| `win_rate` | String (Decimal) | Proportion of winning trades (0–1) |
| `total_pnl` | String (Decimal) | Total profit and loss |
| `total_invested` | String (Decimal) | Total capital invested |
| `roi` | String (Decimal) | Return on investment |
| `markets_traded` | Integer | Number of unique markets traded |
| `last_active` | String (ISO 8601) | Timestamp of last activity |
| `avg_position_size` | String (Decimal) | Average trade position size |
| `best_trade` | String (Decimal) | Largest profitable trade |
| `worst_trade` | String (Decimal) | Largest losing trade |
| `sharpe_ratio` | String (Decimal) | Risk-adjusted return (Sharpe ratio) |
| `sortino_ratio` | String (Decimal) | Downside risk-adjusted return |
| `calmar_ratio` | String (Decimal) | Return relative to max drawdown |
| `max_drawdown` | String (Decimal) | Maximum peak-to-trough decline |
| `profit_factor` | String (Decimal) | Gross profit divided by gross loss |
| `ulcer_index` | String (Decimal) | Drawdown severity index |
| `gain_to_pain_ratio` | String (Decimal) | Total gains divided by total losses |
| `drawdown_frequency` | String (Decimal) | Frequency of drawdowns |
| `recovery_time_avg` | String (Decimal) | Average time to recover from drawdowns |
| `performance_trend` | String | Performance trend classification (e.g., improving / stable / declining) |
| `edge_decay` | String (Decimal) | Measure of strategy performance degradation |
| `performance_by_category` | JSON | Performance breakdown by market category |
| `category_diversity_score` | String (Decimal) | Diversification score across categories |
| `days_active` | Integer | Number of active trading days |
| `annualized_return` | String (Decimal) | Annualized return |
| `win_rate_last_30d` | String (Decimal) | Win rate over last 30 days |
| `win_rate_z_score` | String (Decimal) | Statistical deviation of win rate |
| `suspicious_win_rate_flag` | Boolean | TRUE if win rate is statistically suspicious |
| `dominant_market_id` | String | Market contributing most PnL |
| `dominant_market_pnl` | String (Decimal) | PnL from dominant market |
| `market_concentration_ratio` | String (Decimal) | Concentration of returns in top market |
| `num_markets_traded` | Integer | Total distinct markets traded |
| `single_market_dependence_flag` | Boolean | TRUE if wallet depends heavily on one market |
| `suspicious_timing_trades` | Integer | Number of trades flagged for suspicious timing |
| `total_timed_trades` | Integer | Total trades evaluated for timing analysis |
| `timing_hit_rate` | String (Decimal) | Success rate of timing-based trades |
| `timing_z_score` | String (Decimal) | Statistical deviation of timing performance |
| `timing_anomaly_flag` | Boolean | TRUE if anomalous timing behavior detected |
| `stddev_position_size` | String (Decimal) | Standard deviation of trade size |
| `coefficient_of_variation` | String (Decimal) | Relative variability of position size |
| `position_size_volatility_flag` | Boolean | TRUE if position sizing is unusually volatile |
| `similar_wallets_count` | Integer | Number of wallets with correlated behavior |
| `trade_timing_correlation_max` | String (Decimal) | Maximum timing correlation with other wallets |
| `sybil_risk_score` | String (Decimal) | Probability score of Sybil behavior |
| `sybil_risk_flag` | Boolean | TRUE if Sybil risk detected |
| `perfect_entry_count` | Integer | Count of statistically perfect entries |
| `perfect_exit_count` | Integer | Count of statistically perfect exits |
| `total_closed_positions` | Integer | Total fully closed positions |
| `perfect_timing_score` | String (Decimal) | Composite perfect timing score |
| `perfect_timing_flag` | Boolean | TRUE if timing performance is statistically abnormal |
| `combined_risk_score` | String (Decimal) | Aggregate behavioral risk score |
| `risk_level` | String | Risk classification (e.g., LOW / MEDIUM / HIGH) |
| `flagged_metrics` | Array\[String] | List of triggered risk metric identifiers |
| `statistical_confidence` | String (Decimal) | Confidence level of statistical evaluation |
| `curve_smoothness` | String (Decimal) | Smoothness metric of equity curve |
| `equity_curve_pattern` | String | Equity curve pattern classification |
| `trade_size_stdev` | String (Decimal) | Standard deviation of trade sizes |
| `max_position_pct` | String (Decimal) | Maximum single position as % of capital |
| `position_size_consistency` | String (Decimal) | Consistency metric of position sizing |
Example Response
```bash
{
"timestamp": "",
"params": {
"proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
"window_days": "3"
},
"pagination": {
"limit": 100,
"offset": 0,
"has_more": true
},
"data": {
"results": [
{
"annualized_return": 4.7138,
"avg_position_size": 2379.96,
"best_trade": 75126.54,
"calculation_window_days": 3,
"calmar_ratio": null,
"category_diversity_score": 1.6501,
"coefficient_of_variation": 3.9035,
"combined_risk_score": 10,
"curve_smoothness": 0.0292,
"date": "2026-03-15T00:00:00Z",
"date_range_end": "2026-03-15T00:00:00Z",
"date_range_start": "2026-03-13T00:00:00Z",
"days_active": 3,
"dominant_market_id": "0x42a016b0a4bdf4de840334551b04bda95fcf02e4626c60bb49e3b1f1530067a3",
"dominant_market_pnl": -68490.68,
"drawdown_frequency": 0,
"edge_decay": null,
"equity_curve_pattern": "volatile",
"flagged_metrics": "{position_size_volatility}",
"gain_to_pain_ratio": 100,
"last_active": "2026-03-15T23:59:59.999999Z",
"losing_trades": 2086,
"market_concentration_ratio": 0.029,
"markets_traded": 3146,
"max_drawdown": 0,
"max_position_pct": 0.3048,
"num_markets_traded": 3146,
"perfect_entry_count": 1204,
"perfect_exit_count": 0,
"perfect_timing_flag": false,
"perfect_timing_score": 0.2258,
"performance_by_category": "W3sicG5sIjogMTYxNzE3LjY4LCAidHJhZGVzIjogNjQwMCwgImNhdGVnb3J5IjogIk90aGVyIn0sIHsicG5sIjogNTgzMDguNTgsICJ0cmFkZXMiOiAyODUsICJjYXRlZ29yeSI6ICJXb3JsZCBFdmVudHMifSwgeyJwbmwiOiA0NzI1OS45OSwgInRyYWRlcyI6IDkzNSwgImNhdGVnb3J5IjogIlNwb3J0cyJ9LCB7InBubCI6IDIyNzk5LjEyLCAidHJhZGVzIjogODIsICJjYXRlZ29yeSI6ICJTY2llbmNlICYgVGVjaCJ9XQ==",
"performance_trend": "improving",
"position_size_consistency": 0,
"position_size_volatility_flag": true,
"profit_factor": 1.0972,
"proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
"recovery_time_avg": 0,
"risk_level": "LOW",
"roi": 3.8743,
"sharpe_ratio": 50,
"similar_wallets_count": 0,
"single_market_dependence_flag": false,
"sortino_ratio": null,
"statistical_confidence": 0.9966,
"stddev_position_size": 4645.09,
"suspicious_timing_trades": 0,
"suspicious_win_rate_flag": false,
"sybil_risk_flag": false,
"sybil_risk_score": 0,
"timing_anomaly_flag": false,
"timing_hit_rate": 0,
"timing_z_score": 0.61,
"total_closed_positions": 2666,
"total_invested": 7487360.92,
"total_pnl": 290085.37,
"total_timed_trades": 85719,
"total_trades": 85719,
"trade_size_stdev": 418.9442,
"trade_timing_correlation_max": 0,
"ulcer_index": 0,
"win_rate": 0.522,
"win_rate_last_30d": 0.5133,
"win_rate_z_score": -5.37,
"winning_trades": 2278,
"worst_trade": -83113.9
},
{
"annualized_return": -8.6915,
"avg_position_size": 2045.27,
"best_trade": 51771.41,
"calculation_window_days": 3,
"calmar_ratio": -86.6618,
"category_diversity_score": 0.6255,
"coefficient_of_variation": 4.0603,
"combined_risk_score": 10,
"curve_smoothness": 0.1176,
"date": "2026-03-14T00:00:00Z",
"date_range_end": "2026-03-14T00:00:00Z",
"date_range_start": "2026-03-12T00:00:00Z",
"days_active": 3,
"dominant_market_id": "0x09eb95f347c8ca17d639371297175ed15f397c531e8ef13286382cda2a2595d1",
"dominant_market_pnl": -178633.03,
"drawdown_frequency": 0.3333,
"edge_decay": null,
"equity_curve_pattern": "volatile",
"flagged_metrics": "{position_size_volatility}",
"gain_to_pain_ratio": -0.776,
"last_active": "2026-03-14T23:59:59.999999Z",
"losing_trades": 1452,
"market_concentration_ratio": 0.0507,
"markets_traded": 2704,
"max_drawdown": 0.1003,
"max_position_pct": 0.4194,
"num_markets_traded": 2704,
"perfect_entry_count": 772,
"perfect_exit_count": 0,
"perfect_timing_flag": false,
"perfect_timing_score": 0.172,
"performance_by_category": "W3sicG5sIjogMjI3MzMuMjIsICJ0cmFkZXMiOiA1NiwgImNhdGVnb3J5IjogIlNjaWVuY2UgJiBUZWNoIn0sIHsicG5sIjogMTY5MzcuNDYsICJ0cmFkZXMiOiAyMTMsICJjYXRlZ29yeSI6ICJXb3JsZCBFdmVudHMifSwgeyJwbmwiOiAtODU5Mi43OSwgInRyYWRlcyI6IDUzODMsICJjYXRlZ29yeSI6ICJPdGhlciJ9LCB7InBubCI6IC00MjYxNTQuMzgsICJ0cmFkZXMiOiA4NjMsICJjYXRlZ29yeSI6ICJTcG9ydHMifV0=",
"performance_trend": "improving",
"position_size_consistency": 0,
"position_size_volatility_flag": true,
"profit_factor": 0.8539,
"proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
"recovery_time_avg": 0,
"risk_level": "LOW",
"roi": -7.1437,
"sharpe_ratio": -8.2487,
"similar_wallets_count": 0,
"single_market_dependence_flag": false,
"sortino_ratio": -7.4996,
"statistical_confidence": 0.9963,
"stddev_position_size": 4447.27,
"suspicious_timing_trades": 0,
"suspicious_win_rate_flag": false,
"sybil_risk_flag": false,
"sybil_risk_score": 0,
"timing_anomaly_flag": false,
"timing_hit_rate": 0,
"timing_z_score": 0.53,
"total_closed_positions": 2244,
"total_invested": 5530399.22,
"total_pnl": -395076.48,
"total_timed_trades": 64006,
"total_trades": 72579,
"trade_size_stdev": 350.6233,
"trade_timing_correlation_max": 0,
"ulcer_index": 5.7904,
"win_rate": 0.5131,
"win_rate_last_30d": 0.5118,
"win_rate_z_score": -5.7,
"winning_trades": 1530,
"worst_trade": -178633.03
},
{
"annualized_return": -9.1115,
"avg_position_size": 3108.28,
"best_trade": 104623.85,
"calculation_window_days": 3,
"calmar_ratio": -2.4321,
"category_diversity_score": 0.6386,
"coefficient_of_variation": 4.5459,
"combined_risk_score": 10,
"curve_smoothness": 0.154,
"date": "2026-03-13T00:00:00Z",
"date_range_end": "2026-03-13T00:00:00Z",
"date_range_start": "2026-03-11T00:00:00Z",
"days_active": 3,
"dominant_market_id": "0x09eb95f347c8ca17d639371297175ed15f397c531e8ef13286382cda2a2595d1",
"dominant_market_pnl": -178633.03,
"drawdown_frequency": 0.3333,
"edge_decay": null,
"equity_curve_pattern": "volatile",
"flagged_metrics": "{position_size_volatility}",
"gain_to_pain_ratio": -0.8455,
"last_active": "2026-03-13T23:59:59.999999Z",
"losing_trades": 1315,
"market_concentration_ratio": 0.0407,
"markets_traded": 2177,
"max_drawdown": 3.7464,
"max_position_pct": 0.6436,
"num_markets_traded": 2177,
"perfect_entry_count": 699,
"perfect_exit_count": 0,
"perfect_timing_flag": false,
"perfect_timing_score": 0.1958,
"performance_by_category": "W3sicG5sIjogNTgzNDguNTksICJ0cmFkZXMiOiA0MTM2LCAiY2F0ZWdvcnkiOiAiT3RoZXIifSwgeyJwbmwiOiAyMjE0OC45OCwgInRyYWRlcyI6IDYyLCAiY2F0ZWdvcnkiOiAiU2NpZW5jZSAmIFRlY2gifSwgeyJwbmwiOiAtMjg0LjY4LCAidHJhZGVzIjogMTAxLCAiY2F0ZWdvcnkiOiAiV29ybGQgRXZlbnRzIn0sIHsicG5sIjogLTU4Njk2Ni41LCAidHJhZGVzIjogOTgwLCAiY2F0ZWdvcnkiOiAiU3BvcnRzIn1d",
"performance_trend": "improving",
"position_size_consistency": 0,
"position_size_volatility_flag": true,
"profit_factor": 0.8458,
"proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
"recovery_time_avg": 0,
"risk_level": "LOW",
"roi": -7.4889,
"sharpe_ratio": -11.3139,
"similar_wallets_count": 0,
"single_market_dependence_flag": false,
"sortino_ratio": -9.321,
"statistical_confidence": 0.9963,
"stddev_position_size": 7133.78,
"suspicious_timing_trades": 0,
"suspicious_win_rate_flag": false,
"sybil_risk_flag": false,
"sybil_risk_score": 0,
"timing_anomaly_flag": false,
"timing_hit_rate": 0,
"timing_z_score": 0.48,
"total_closed_positions": 1785,
"total_invested": 6766728.68,
"total_pnl": -506753.6,
"total_timed_trades": 71340,
"total_trades": 71340,
"trade_size_stdev": 536.9849,
"trade_timing_correlation_max": 0,
"ulcer_index": 277.5712,
"win_rate": 0.5064,
"win_rate_last_30d": 0.5117,
"win_rate_z_score": -6.57,
"winning_trades": 1349,
"worst_trade": -178633.03
}
]
}
}
```
***
### Notes
* Use smaller `window_days` values (e.g. `"1"` or `"3"`) to analyze **short-term trading behavior**, while larger windows (e.g. `"7"` or `"15"`) provide a better view of overall strategy consistency.
* Evaluate `roi`, `sharpe_ratio`, and `sortino_ratio` together to understand **profitability relative to risk**, rather than relying on raw PnL alone.
* Monitor `max_drawdown`, `ulcer_index`, and `recovery_time_avg` to assess **how a trader handles losses and recovers from drawdowns**.
* Use `market_concentration_ratio` and `single_market_dependence_flag` to identify wallets that **rely heavily on a small number of markets**, which may increase risk.
* Analyze `position_size_consistency`, `trade_size_stdev`, and `coefficient_of_variation` to understand **how consistently a trader sizes their positions**.
* Check `sybil_risk_score`, `sybil_risk_flag`, and `similar_wallets_count` to detect **coordinated or suspicious trading behavior**.
* Use `performance_trend` and `edge_decay` to determine whether a trader’s **strategy performance is improving, stable, or deteriorating over time**.
* Review `combined_risk_score`, `risk_level`, and `flagged_metrics` to quickly identify wallets with **statistically abnormal or high-risk trading patterns**.