# TopLedger

> Real-time Solana DeFi intelligence platform. REST APIs and MCP tools for tracking wallets, positions, and PnL across 20+ protocols — built for developers and AI agents.

## API Documentation

- [API Reference](https://api.topledger.xyz/api-docs): Interactive API docs (OpenAPI / Scalar) with 60+ endpoints
- [Get Started](https://api.topledger.xyz/#get-started): Sign up and get an API key in seconds

## Core APIs

- [Wallet Analysis](https://api.topledger.xyz/api-docs#tag/wallet-analysis): Full portfolio overview — net worth, all DeFi positions, token holdings, DEX PnL
- [Lending](https://api.topledger.xyz/api-docs#tag/lending): Positions across Kamino, Drift, Jupiter Lend, Loopscale, Project Zero, Huma
- [Perpetuals](https://api.topledger.xyz/api-docs#tag/perpetuals): Open perp positions on Drift, Jupiter Perps, Flash Trade
- [Staking](https://api.topledger.xyz/api-docs#tag/staking): Native SOL staking, Drift insurance, Jupiter DAO, Helium, Seeker, Raydium RAY
- [Liquidity Provisioning](https://api.topledger.xyz/api-docs#tag/lp): LP positions on Meteora DLMM, Meteora DAMM V2, Orca Whirlpool, Raydium CLMM/AMM/CP
- [Yield / Vaults](https://api.topledger.xyz/api-docs#tag/yield): Kamino Vaults, Exponent, Elemental, Loopscale Vaults, Perena, Hylo
- [DEX Trading](https://api.topledger.xyz/api-docs#tag/dex): FIFO-based PnL tracking, per-token positions, daily performance
- [Token Data](https://api.topledger.xyz/api-docs#tag/tokens): Metadata, live prices, supply, market cap, top holders, PnL leaderboards
- [Holdings](https://api.topledger.xyz/api-docs#tag/holdings): On-chain SOL + SPL token balances with real-time USD pricing

## MCP Server for AI Agents

- [MCP SSE Endpoint](https://api.topledger.xyz/mcp/sse): Connect AI agents via Model Context Protocol (SSE transport)
- [MCP Health](https://api.topledger.xyz/mcp/health): Server health check

### MCP Tools Available

- analyze_wallet: Complete portfolio overview with net worth and all DeFi positions
- get_all_lending: Lending positions across 6 protocols
- get_all_perps: Perpetual futures across Drift, Jupiter Perps, Flash Trade
- get_all_staking: Staking positions across 7 protocols
- get_all_lp: Liquidity provider positions across 6 AMMs
- get_all_yield: Yield-bearing positions across 8 protocols
- get_all_rewards: Unclaimed rewards across all protocols
- get_all_dex: DEX trading positions with FIFO PnL
- get_holdings: On-chain token holdings with USD pricing

## Real-Time Streaming

### WebSocket

**Endpoint:** `wss://api.topledger.xyz/ws?api_key=YOUR_KEY`

Channels (subscribe via JSON on the same connection):

- **swaps** — real-time DEX swap events. Filters: dex, token, wallets (up to 100)
  - DEXs: pump-fun, pump-swap, raydium-amm, raydium-cpmm, raydium-clmm, meteora-dlmm, meteora-dbc, orca-whirlpool, moonshot
  - Subscribe: `{ "action": "subscribe", "channel": "swaps" }`
  - Filter by DEX: `{ "action": "subscribe", "channel": "swaps", "dex": "pump-fun" }`
  - Filter by wallets: `{ "action": "subscribe", "channel": "swaps", "wallets": ["W1", "W2"] }`

- **creations** — real-time token creation events from bonding curve platforms
  - Platforms: pump-fun, raydium-launchlab, letsbonk, bonkers, surge, meteora-dbc, bags, believe, jup-studio, anoncoin, soar, moonshot, daosfun, sugar, boop-fun
  - Subscribe: `{ "action": "subscribe", "channel": "creations" }`

- **prices** — real-time token price updates from DEX trades
  - Subscribe: `{ "action": "subscribe", "channel": "prices", "mints": ["MINT1", "MINT2"] }` (up to 100 mints)

### Trending Pairs WebSocket (separate connection)

**Endpoint:** `wss://api.topledger.xyz/ws/trending-pairs`

Live bonding curve token updates with trading metrics, holder data, and pool liquidity.
- Subscribe: `{ "action": "subscribe", "dex": "*" }` (or specific: `"pump-fun"`)

### Kafka Direct Access (Business+)

Topics: solana-dex-swaps, solana-token-creations, solana-token-prices (Protobuf + LZ4)

## Protocols Covered

Kamino, Drift, Jupiter (Perps, Lend, DAO), Meteora (DLMM, DAMM V2), Orca Whirlpool, Raydium (CLMM, AMM, CP Swap), Loopscale, Project Zero, Flash Trade, Helium, Seeker, Huma Finance, Exponent, Elemental, Perena, Hylo, Carrot, PumpFun, Moonshot, and more.

## Pricing

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

## Contact

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