cURL
curl --request POST \
--url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"agent_id": 579,
"params": {
"wallet_address": "ALL",
"leaderboard_period": "1d"
},
"pagination": { "limit": 10, "offset": 0 },
"formatter_config": { "format_type": "raw" }
}'import requests
response = requests.post(
"https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
headers={"Authorization": "Bearer YOUR_TOKEN"},
json={
"agent_id": 579,
"params": {
"wallet_address": "ALL",
"leaderboard_period": "1d",
},
"pagination": {"limit": 10, "offset": 0},
"formatter_config": {"format_type": "raw"},
},
)
print(response.json())const response = await fetch(
"https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
{
method: "POST",
headers: {
Authorization: "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({
agent_id: 579,
params: {
wallet_address: "ALL",
leaderboard_period: "1d",
},
pagination: { limit: 10, offset: 0 },
formatter_config: { format_type: "raw" },
}),
}
);
const data = await response.json();{
"timestamp": "<string>",
"params": {
"wallet_address": "<string>",
"leaderboard_period": "<string>"
},
"pagination": {
"limit": 123,
"offset": 123,
"has_more": true
},
"data": {
"results": [
{}
]
},
"request_id": "<string>"
}Polymarket
PnL Leaderboard
Falcon Leaderboard API
POST
/
api
/
v2
/
semantic
/
retrieve
/
parameterized
cURL
curl --request POST \
--url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"agent_id": 579,
"params": {
"wallet_address": "ALL",
"leaderboard_period": "1d"
},
"pagination": { "limit": 10, "offset": 0 },
"formatter_config": { "format_type": "raw" }
}'import requests
response = requests.post(
"https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
headers={"Authorization": "Bearer YOUR_TOKEN"},
json={
"agent_id": 579,
"params": {
"wallet_address": "ALL",
"leaderboard_period": "1d",
},
"pagination": {"limit": 10, "offset": 0},
"formatter_config": {"format_type": "raw"},
},
)
print(response.json())const response = await fetch(
"https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
{
method: "POST",
headers: {
Authorization: "Bearer YOUR_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({
agent_id: 579,
params: {
wallet_address: "ALL",
leaderboard_period: "1d",
},
pagination: { limit: 10, offset: 0 },
formatter_config: { format_type: "raw" },
}),
}
);
const data = await response.json();{
"timestamp": "<string>",
"params": {
"wallet_address": "<string>",
"leaderboard_period": "<string>"
},
"pagination": {
"limit": 123,
"offset": 123,
"has_more": true
},
"data": {
"results": [
{}
]
},
"request_id": "<string>"
}Platform: Polymarket
Endpoint:
Authentication: Bearer token
Endpoint:
POST /v2/semantic/retrieve/parameterizedAuthentication: Bearer token
Query parameters
All requests useagent_id 579 (PnL Leaderboard). Set filters inside params in the playground — all values must be strings.
| Parameter | Type | Description |
|---|---|---|
wallet_address | String | Use "ALL" for all wallets, or a specific wallet address. |
leaderboard_period | String | Time window: 1d, 3d, 7d, or 30d. |
Example Request
curl --request POST \
--url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"agent_id": 579,
"params": {
"wallet_address": "ALL",
"leaderboard_period": "1d"
},
"pagination": {
"limit": 10,
"offset": 0
},
"formatter_config": {
"format_type": "raw"
}
}'
import requests
response = requests.post(
"https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
headers={"Authorization": "Bearer YOUR_TOKEN"},
json={
"agent_id": 579,
"params": {
"wallet_address": "ALL",
"leaderboard_period": "1d"
},
"pagination": {
"limit": 10,
"offset": 0
},
"formatter_config": {
"format_type": "raw"
}
}
)
print(response.json())
const response = await fetch("https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json"
},
body: JSON.stringify({
"agent_id": 579,
"params": {
"wallet_address": "ALL",
"leaderboard_period": "1d"
},
"pagination": {
"limit": 10,
"offset": 0
},
"formatter_config": {
"format_type": "raw"
}
})
});
const data = await response.json();
Example Response
{
"timestamp": "2025-01-15T12:00:00Z",
"params": {
"min_win_rate_15d": "0.45",
"max_win_rate_15d": "0.95",
"min_roi_15d": "0",
"min_total_trades_15d": "50",
"max_total_trades_15d": "100000",
"min_pnl_15d": "5000",
"sort_by": "roi"
},
"pagination": {
"limit": 10,
"offset": 0,
"has_more": true
},
"data": {
"results": [
{
"leaderboard_rank": 1,
"wallet": "0x0720803c7cb0d0c5a928787b3b7ea148c6831cdb",
"tier": "A",
"f_score": 87.4,
"roi_pct_15d": 41.5,
"win_rate_pct_15d": 0.72,
"sharpe_ratio_15d": 1.25,
"total_trades_15d": 120,
"markets_traded_15d": 18,
"total_pnl_15d": 12500.5,
"total_volume_15d": 3600711.99,
"trajectory": "Improving"
}
]
},
"request_id": "req_abc123"
}
Response fields
| Field | Type | Description |
|---|---|---|
rank | Integer | Leaderboard rank within the selected period |
address | String | Wallet address |
total_pnl | String (decimal) | Total profit and loss for the period (negative values indicate a loss) |
roi | String (decimal) | Return on investment |
win_rate | String (decimal) | Win percentage (0–1) |
sharpe_ratio | String (decimal) | Risk-adjusted performance metric |
total_volume | String (decimal) | Total trading volume |
markets_traded | Integer | Number of unique markets traded |
total_trades | Integer | Total number of trades executed |
Authorizations
Your Falcon API key from the dashboard
Body
application/json
Filter parameters. All values must be strings.
PnL Leaderboard agent ID.
Available options:
579 Response
Success