# 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, governance deposits, Jupiter-verified token holdings, DEX PnL |
| GET /api/wallets/{wallet}/holdings | Native SOL plus Jupiter-verified SPL / Token-2022 balances with USD pricing. Query: ?min_value_usd=1 |
| GET /api/wallets/{wallet}/all-lending | Aggregated lending across Kamino, Project Zero, Loopscale, Jupiter Lend, Jupiter Offerbook, Huma, Carrot |
| GET /api/wallets/{wallet}/all-perps | Aggregated perps across Drift, Jupiter Perps, Flash Trade, Parcl |
| GET /api/wallets/{wallet}/all-staking | Aggregated staking: native SOL, Drift IF, Jupiter DAO with locked/unlocked JUP breakdown, Helium, Seeker, Huma, Raydium, Kamino, Pyth, Wormhole MultiGov, Parcl, M3M3, Solomon, Streamflow |
| GET /api/wallets/{wallet}/all-governance | Aggregated governance deposits across SPL Governance / Realms, Tribeca, and Jupiter Lock |
| GET /api/wallets/{wallet}/all-lp | Aggregated LP across Meteora DLMM, DAMM V2, Orca Whirlpool, Raydium CLMM/AMM/CP, Parcl including pending withdrawals |
| GET /api/wallets/{wallet}/all-yield | Aggregated yield: Kamino Vaults, Hylo, Carrot, Perena, Exponent v1 YT/LP plus v2 CLMM liquidity and Strategy Vaults, Elemental, Huma, HawkFi, 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}/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}/project-zero/lending | Project Zero (marginfi v2) full lending position |
| GET /api/wallets/{wallet}/loopscale/loans | Loopscale active loans |
| GET /api/wallets/{wallet}/loopscale/advanced-lending | Loopscale direct lender strategy supply positions |
| 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}/jupiter-offerbook/positions | Jupiter Offerbook fixed-term P2P lending: escrow deposits, open offers, borrower loans, lender loans |
| GET /api/wallets/{wallet}/huma/positions | Huma Finance lending positions |
| GET /api/wallets/{wallet}/carrot/lending | Carrot lending deposits and borrows |

## 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 |
| GET /api/wallets/{wallet}/parcl/positions | Parcl V3 margin accounts and raw market 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}/exponent/v2/liquidity | Exponent v2 CLMM liquidity positions with PT/SY withdrawal value |
| GET /api/wallets/{wallet}/exponent/v2/strategy-vaults | Exponent v2 Strategy Vault share-token positions and pending withdrawals |
| GET /api/wallets/{wallet}/elemental/positions | Elemental vault deposits |
| GET /api/wallets/{wallet}/hawkfi/positions | HawkFi yield positions |

## 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 |
| GET /api/wallets/{wallet}/parcl/lp | Parcl V3 LP positions and pending withdrawal settlement requests |

## 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 with locked JUP and unlocked partial-unstaking totals |
| 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 |
| GET /api/wallets/{wallet}/kamino/staking | Kamino KMNO staking positions |
| GET /api/wallets/{wallet}/huma/staking | Huma HUMA staking positions |
| GET /api/wallets/{wallet}/pyth/staking | Pyth governance staking positions |
| GET /api/wallets/{wallet}/streamflow/staking | Streamflow staking positions |
| GET /api/wallets/{wallet}/parcl/staking | Parcl PRCL staking positions |
| GET /api/wallets/{wallet}/wormhole/staking | Wormhole MultiGov W staking positions |
| GET /api/wallets/{wallet}/meteora/m3m3/staking | Meteora M3M3 Stake2Earn staking positions |
| GET /api/wallets/{wallet}/solomon/positions | Solomon USDv and sUSDv positions |

## Governance

| Endpoint | Description |
|----------|-------------|
| GET /api/wallets/{wallet}/realms/deposits | SPL Governance / Realms token-owner deposits |
| GET /api/wallets/{wallet}/jupiter-lock/vesting | Jupiter Lock vesting escrows |
| GET /api/wallets/{wallet}/tribeca/escrows | Tribeca vote-escrow governance deposits |

## 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, timestamp, and dependency checks |

---

## 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

10 tools: analyze_wallet, get_all_lending, get_all_perps, get_all_staking, get_all_governance, 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

## Pay.sh Access

Gateway: https://api.topledger.xyz/pay
Health: https://api.topledger.xyz/pay/__402/health

Pay.sh exposes the wallet intelligence endpoints through MPP-paid HTTP 402 challenges. Agents can call the gateway without a pre-issued TopLedger API key; the gateway injects upstream authentication internally after payment.

Pricing: $0.0004 per request ($0.40 per 1,000 calls), settled in Solana USDC.

## 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