# 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, governance deposits, Jupiter-verified token holdings, DEX PnL
- [Lending](https://api.topledger.xyz/api-docs#tag/lending): Positions across Kamino, Drift, Jupiter Lend, Jupiter Offerbook, Loopscale direct strategies/loans, Project Zero, Huma
- [Perpetuals](https://api.topledger.xyz/api-docs#tag/perpetuals): Open perp positions on Drift, Jupiter Perps, Flash Trade, Parcl
- [Staking](https://api.topledger.xyz/api-docs#tag/staking): Native SOL staking, Drift insurance, Jupiter DAO locked/unlocked JUP, Helium, Seeker, Raydium RAY, Pyth, Parcl, Wormhole MultiGov, M3M3, Solomon, Streamflow
- [Governance](https://api.topledger.xyz/api-docs#tag/governance): SPL Governance / Realms, Tribeca token deposits, Jupiter Lock vesting
- [Liquidity Provisioning](https://api.topledger.xyz/api-docs#tag/lp): LP positions on Meteora DLMM, Meteora DAMM V2, Orca Whirlpool, Raydium CLMM/AMM/CP, Parcl including pending withdrawals
- [Yield / Vaults](https://api.topledger.xyz/api-docs#tag/yield): Kamino Vaults, Exponent YT/LP, v2 CLMM liquidity and v2 Strategy Vaults, 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): Native SOL plus Jupiter-verified SPL / Token-2022 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

## Pay.sh Access

- [Pay.sh Gateway](https://api.topledger.xyz/pay): Agent-native pay-per-call access to wallet intelligence endpoints
- [Pay.sh Health](https://api.topledger.xyz/pay/__402/health): Gateway health check
- Pricing: $0.0004 per request ($0.40 per 1,000 calls), settled in Solana USDC through MPP
- Agents can use Pay.sh without a pre-issued TopLedger API key; the gateway handles upstream authentication internally

### MCP Tools Available

- analyze_wallet: Complete portfolio overview with net worth and all DeFi positions
- get_all_lending: Lending positions across 7 protocols, including Jupiter Offerbook
- get_all_perps: Perpetual futures across Drift, Jupiter Perps, Flash Trade, Parcl
- get_all_staking: Staking positions across 13+ protocols, including Streamflow
- get_all_governance: Governance token deposits across SPL Governance / Realms, Tribeca DAOs, and Jupiter Lock vesting
- get_all_lp: Liquidity provider positions across 6 AMMs
- get_all_yield: Yield-bearing positions across 9+ protocols
- get_all_rewards: Unclaimed rewards across all protocols
- get_all_dex: DEX trading positions with FIFO PnL
- get_holdings: Native SOL plus Jupiter-verified 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, Lock), Streamflow, Parcl, Meteora (DLMM, DAMM V2, M3M3), Orca Whirlpool, Raydium (CLMM, AMM, CP Swap), Loopscale, Project Zero, Flash Trade, Helium, Seeker, Huma Finance, Pyth, Realms, Tribeca, HawkFi, Solomon, 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