# TopLedger — Full API Reference

> Complete endpoint listing for the TopLedger Solana DeFi Intelligence API.
> For a shorter overview, see [llms.txt](https://api.topledger.xyz/llms.txt).

Base URL: `https://api.topledger.xyz`
Auth header: `x-api-key: YOUR_KEY`

---

## Portfolio Overview

| Endpoint | Description |
|----------|-------------|
| GET /api/wallets/{wallet}/analyze | Full portfolio: net worth, all DeFi positions, token holdings, DEX PnL |
| GET /api/wallets/{wallet}/holdings | On-chain SOL + SPL token balances with USD pricing. Query: ?min_value_usd=1 |
| GET /api/wallets/{wallet}/all-lending | Aggregated lending across Kamino, Project Zero, Loopscale, Jupiter Lend, Huma, Carrot |
| GET /api/wallets/{wallet}/all-perps | Aggregated perps across Drift, Jupiter Perps, Flash Trade |
| GET /api/wallets/{wallet}/all-staking | Aggregated staking: native SOL, Drift IF, Jupiter DAO, Helium, Seeker, Huma, Raydium |
| GET /api/wallets/{wallet}/all-lp | Aggregated LP across Meteora DLMM, DAMM V2, Orca Whirlpool, Raydium CLMM/AMM/CP |
| GET /api/wallets/{wallet}/all-yield | Aggregated yield: Kamino Vaults, Hylo, Carrot, Perena, Exponent, Elemental, Loopscale |
| GET /api/wallets/{wallet}/all-rewards | Unclaimed rewards across Drift, Kamino, Project Zero, Loopscale |
| GET /api/wallets/{wallet}/all-dex | DEX trading positions with FIFO PnL. Query: ?limit=50 |
| POST /api/wallets/batch | Batch wallet analysis. Body: { "wallets": ["W1", "W2"], "include": ["holdings", "lending", ...] } |

## DEX Trading & PnL

| Endpoint | Description |
|----------|-------------|
| GET /api/wallets/{wallet} | All DEX positions for a wallet (per-token FIFO PnL) |
| GET /api/wallets/{wallet}/{mint} | Single token position + unrealized PnL |
| GET /api/wallets/{wallet}/portfolio | Hero endpoint: full portfolio with 7-day performance |
| GET /api/wallets/{wallet}/pnl/summary | 7-day PnL summary |
| GET /api/wallets/{wallet}/pnl/daily | Daily PnL breakdown (all tokens) |
| GET /api/wallets/{wallet}/pnl/{mint}/daily | Daily PnL for a specific token |
| GET /api/wallets/{wallet}/trades/daily | Daily trade volume stats |
| GET /api/wallets/{wallet}/trades/{mint} | Trade history for a specific token |
| GET /api/wallets/leaderboard/{mint} | Top traders by realized PnL for a token |

## Lending

| Endpoint | Description |
|----------|-------------|
| GET /api/wallets/{wallet}/kamino/lending | Full Kamino lending: deposits, borrows, health factor, liquidation risk |
| GET /api/wallets/{wallet}/kamino/lending/deposits | Kamino deposit positions only |
| GET /api/wallets/{wallet}/kamino/lending/borrows | Kamino borrow positions only |
| GET /api/wallets/{wallet}/kamino/lending/health | Kamino health factor and risk metrics |
| GET /api/wallets/{wallet}/project-zero/lending | Project Zero (marginfi v2) full lending position |
| GET /api/wallets/{wallet}/project-zero/lending/deposits | Project Zero deposits |
| GET /api/wallets/{wallet}/project-zero/lending/borrows | Project Zero borrows |
| GET /api/wallets/{wallet}/loopscale/loans | Loopscale active loans |
| GET /api/wallets/{wallet}/loopscale/loops | Loopscale leveraged lending loops |
| GET /api/wallets/{wallet}/jupiter-lend/earn | Jupiter Lend earn deposits (fToken → underlying) |
| GET /api/wallets/{wallet}/jupiter-lend/borrow | Jupiter Lend borrow positions (NFT-based) |
| GET /api/wallets/{wallet}/huma/positions | Huma Finance lending positions |

## Perpetuals

| Endpoint | Description |
|----------|-------------|
| GET /api/wallets/{wallet}/drift/positions | Drift spot + perp positions with aggregated view |
| GET /api/wallets/{wallet}/drift/health | Drift account health + margin ratios |
| GET /api/wallets/{wallet}/drift/lp | Drift perp AMM LP positions |
| GET /api/wallets/{wallet}/drift/funding | Drift funding payment history |
| GET /api/wallets/{wallet}/jupiter-perps/positions | Jupiter Perps open positions with Pyth prices |
| GET /api/wallets/{wallet}/jupiter-perps/pnl | Jupiter Perps PnL summary |
| GET /api/wallets/{wallet}/flash/positions | Flash Trade perpetual positions |

## Yield & Stablecoins

| Endpoint | Description |
|----------|-------------|
| GET /api/wallets/{wallet}/kamino/vaults | Kamino vault deposits (shares → underlying via exchange rate) |
| GET /api/wallets/{wallet}/kamino/liquidity | Kamino managed liquidity positions |
| GET /api/wallets/{wallet}/loopscale/vaults | Loopscale vault deposits with USD values |
| GET /api/wallets/{wallet}/hylo/positions | Hylo exchange positions |
| GET /api/wallets/{wallet}/carrot/positions | Carrot protocol positions |
| GET /api/wallets/{wallet}/perena/positions | Perena stablecoin yield positions |
| GET /api/wallets/{wallet}/exponent/positions | Exponent yield tokenization positions |
| GET /api/wallets/{wallet}/elemental/positions | Elemental vault deposits |

## LP Positions

| Endpoint | Description |
|----------|-------------|
| GET /api/wallets/{wallet}/meteora-dlmm/liquidity | Meteora DLMM concentrated LP positions |
| GET /api/wallets/{wallet}/meteora-damm-v2/liquidity | Meteora DAMM V2 LP positions |
| GET /api/wallets/{wallet}/orca-whirlpool/liquidity | Orca Whirlpool concentrated LP positions |
| GET /api/wallets/{wallet}/raydium-clmm/liquidity | Raydium CLMM LP positions |
| GET /api/wallets/{wallet}/raydium-amm/liquidity | Raydium AMM V4 LP positions |
| GET /api/wallets/{wallet}/raydium-cp-swap/liquidity | Raydium CP Swap LP positions |

## Staking

| Endpoint | Description |
|----------|-------------|
| GET /api/wallets/{wallet}/staking/native | Native SOL stake accounts — validator, status, epoch, USD values |
| GET /api/wallets/{wallet}/drift/staking | Drift insurance fund staking positions |
| GET /api/wallets/{wallet}/jupiter-dao/staking | Jupiter DAO veJUP vote-escrow staking |
| GET /api/wallets/{wallet}/flash/staking | Flash Trade sFLP/FAF staking |
| GET /api/wallets/{wallet}/helium/staking | Helium veHNT/veIOT/veMOBILE staking |
| GET /api/wallets/{wallet}/seeker/staking | Seeker (Solana Mobile) SKR staking — guardian delegation |
| GET /api/wallets/{wallet}/raydium/staking | Raydium RAY staking (Farm V3) — staked RAY, pending rewards, vote-locked governance |

## Rewards

| Endpoint | Description |
|----------|-------------|
| GET /api/wallets/{wallet}/kamino/rewards | Kamino farm pending rewards |
| GET /api/wallets/{wallet}/drift/rewards | Drift Fuel rewards |
| GET /api/wallets/{wallet}/project-zero/rewards | Project Zero emissions |
| GET /api/wallets/{wallet}/loopscale/rewards | Loopscale pending rewards |

## Tokens

| Endpoint | Description |
|----------|-------------|
| GET /api/tokens/{mint} | Token metadata + current price + supply + market cap |
| GET /api/tokens/{mint}/price | Current price, 24h change, market cap |
| GET /api/tokens/{mint}/holders | Top token holders (address, balance, %) |
| GET /api/tokens/{mint}/leaderboard | Top traders by realized PnL |
| POST /api/tokens/batch | Batch token info. Body: { "mints": ["M1", "M2"] } |
| POST /api/tokens/leaderboard/batch | Batch leaderboards. Body: { "mints": ["M1", "M2"] } |

## Health

| Endpoint | Description |
|----------|-------------|
| GET /api/health | Service health check — returns { status: "ok" } |

---

## WebSocket Streaming

### Main WebSocket — wss://api.topledger.xyz/ws?api_key=YOUR_KEY

Three channels on a single connection:

### Channel: swaps
Real-time DEX swap events.

Subscribe: `{ "action": "subscribe", "channel": "swaps" }`
Filter by DEX: `{ "action": "subscribe", "channel": "swaps", "dex": "pump-fun" }`
Filter by token: `{ "action": "subscribe", "channel": "swaps", "token": "MINT" }`
Filter by wallets: `{ "action": "subscribe", "channel": "swaps", "wallets": ["W1", "W2"] }` (up to 100)
Unsubscribe: `{ "action": "unsubscribe", "channel": "swaps" }`

Available DEXs: pump-fun, pump-swap, raydium-amm, raydium-cpmm, raydium-clmm, meteora-dlmm, meteora-dbc, orca-whirlpool, moonshot

Message: `{ "type": "swap", "channel": "swaps", "data": { ... } }`

### Channel: creations
Real-time token creation events from bonding curve platforms.

Subscribe: `{ "action": "subscribe", "channel": "creations" }`
Filter: `{ "action": "subscribe", "channel": "creations", "platforms": ["pump-fun"] }`

Available platforms: pump-fun, raydium-launchlab, letsbonk, bonkers, surge, meteora-dbc, bags, believe, jup-studio, anoncoin, soar, moonshot, daosfun, sugar, boop-fun

Message: `{ "type": "creation", "channel": "creations", "data": { ... } }`

### Channel: prices
Real-time token price updates from DEX trades.

Subscribe: `{ "action": "subscribe", "channel": "prices", "mints": ["MINT1", "MINT2"] }` (up to 100)
Omit mints for all prices.

Message: `{ "type": "price", "channel": "prices", "data": { "mint": "...", "price_sol": 0.001, "price_usd": 0.15, "timestamp": 1711234567890 } }`

### Keepalive
Send: `{ "action": "ping" }` → Receive: `{ "type": "pong", "timestamp": ... }`

---

### Trending Pairs WebSocket — wss://api.topledger.xyz/ws/trending-pairs

Separate connection for live bonding curve token updates with trading metrics, holder data, and pool liquidity.

Subscribe all: `{ "action": "subscribe", "dex": "*" }`
Subscribe specific: `{ "action": "subscribe", "dex": ["pump-fun", "raydium-launchlab"] }`

Available platforms: pump-fun, raydium-launchlab, meteora-dbc, letsbonk, bags, believe, jup-studio, anoncoin

Message fields: mint, name, symbol, dex, creator, price_usd, market_cap, liquidity_usd, buy_count, sell_count, buy_volume_24h, sell_volume_24h, total_volume_24h, holder_count, top10_holders_pct, dev_holding_pct, bonding_curve_pct, is_migrated, supply, decimals

---

## Kafka Direct Access (Business+ plans)

| Topic | Format | Content |
|-------|--------|---------|
| solana-dex-swaps | Protobuf (LZ4) | All DEX trade events |
| solana-token-creations | Protobuf (LZ4) | Token creation events |
| solana-token-prices | Protobuf (LZ4) | Price updates |

Contact nitin@topledger.xyz for Kafka broker credentials and protobuf schemas.

---

## MCP Server for AI Agents

SSE Endpoint: https://api.topledger.xyz/mcp/sse
Health: https://api.topledger.xyz/mcp/health

9 tools: analyze_wallet, get_all_lending, get_all_perps, get_all_staking, get_all_lp, get_all_yield, get_all_rewards, get_all_dex, get_holdings

Each tool takes a `wallet` (Solana address) parameter and returns JSON.

---

## Authentication

All endpoints require an API key via `x-api-key` header.
WebSocket auth via query: `?api_key=YOUR_KEY`
Get a free key at https://api.topledger.xyz

## Pricing

- Free ($0/mo): 50K credits, all REST endpoints, basic MCP tools, 60 req/min
- Pro ($199/mo): 1M credits, WebSocket (1 connection), full MCP server, 600 req/min
- Business ($799/mo): 20M credits, WebSocket (5 connections), Kafka streaming, 100 wallet filters, 2,000 req/min
- Enterprise (Custom): Unlimited credits, dedicated connections, custom data pipelines, 99.7% SLA

1 API call = 1 credit.

## Contact

- Website: https://api.topledger.xyz
- Email: nitin@topledger.xyz
- Twitter: https://x.com/topabordefi