> ## Documentation Index > Fetch the complete documentation index at: https://docs.mobula.io/llms.txt > Use this file to discover all available pages before exploring further. # Get Wallet Positions History > Paginated list of every CLOSED position cycle the wallet has traded, across every token. Each entry carries its own realized PnL, entry/exit dates, and token metadata. **Alpha** — This endpoint is in early access. Response shape, field names, and sort/pagination semantics may change without notice. ### What it returns Unlike `/wallet/positions` which returns one row per token (lifetime aggregate), this endpoint returns **one row per closed trading cycle**. A trader who bought/sold the same coin three separate times will appear three times here, each with its own realized PnL — exactly as they would on an exchange trade-history panel. Currently open positions are excluded. Use [`/wallet/positions`](wallet-positions) or [`/wallet/position-history`](wallet-position-history) to see them. ### Query Parameters | Parameter | Type | Required | Description | | ---------- | ------ | -------- | --------------------------------------------------------------------------------------- | | `wallet` | string | Yes | Wallet address. | | `chainIds` | string | No | Comma-separated list of chain IDs (e.g. `evm:1,solana:solana`). If omitted, all chains. | | `limit` | number | No | Page size. `1–200`, default `50`. | | `offset` | number | No | Pagination offset, default `0`. | | `sortBy` | string | No | One of `exitDate` (default), `entryDate`, `realizedPnl`. | | `order` | string | No | `asc` or `desc` (default). | ### Usage Examples **Top 10 most-profitable closed trades:** ```bash theme={null} curl -X GET "https://api.mobula.io/api/2/wallet/positions-history?wallet=4sAUSQFdvWRBxR8UoLBYbw8CcXuwXWxnN8pXa4mtm5nU&sortBy=realizedPnl&order=desc&limit=10" ``` **Most recent exits, Solana only:** ```bash theme={null} curl -X GET "https://api.mobula.io/api/2/wallet/positions-history?wallet=4sAUSQFdvWRBxR8UoLBYbw8CcXuwXWxnN8pXa4mtm5nU&chainIds=solana:solana&sortBy=exitDate&order=desc&limit=50" ``` ### Sample Response ```json theme={null} { "data": [ { "token": { "address": "...", "chainId": "solana:solana", "symbol": "SHEEP", "name": "SHEEP token", "decimals": 6, "logo": "https://...", "blockchain": "Solana" // ... full TokenDetailsOutput shape }, "cycle": { "isOpen": false, "entryDate": "2026-03-13T13:12:43.000Z", "exitDate": "2026-03-13T13:48:11.000Z", "buys": 3, "sells": 15, "volumeBuyToken": 50000000, "volumeSellToken": 50000000, "volumeBuyUSD": 8200.00, "volumeSellUSD": 25142.42, "avgBuyPriceUSD": 0.000164, "avgSellPriceUSD": 0.000503, "realizedPnlUSD": 16942.42, "unrealizedPnlUSD": 0, "totalPnlUSD": 16942.42, "remainingBalance": 0, "currentPriceUSD": null, "feesUSD": 18.2, "swapCount": 18 } } ], "pagination": { "total": 4184, "page": 1, "offset": 0, "limit": 50, "pageEntries": 50 } } ``` ### Cycle semantics Each `cycle` object uses the exact same field set as [`/wallet/position-history`](wallet-position-history). Refer to that page for per-field documentation. Because this endpoint filters to closed cycles only, `isOpen` is always `false`, `exitDate` is always set, `remainingBalance` is `0` (±dust), `unrealizedPnlUSD` is `0`, and `currentPriceUSD` is `null`. ### Performance The endpoint scans all trade swaps for the wallet once (server-side Postgres bitmap index on `swap_recipient_id` / `transaction_sender_address_id`), groups them by token, detects cycles in-memory, and paginates the global list. Candidate tokens are pre-filtered to those with at least one sell on record — a token never sold cannot have a closed cycle. Typical latency: | Wallet size | Latency | | --------------------------- | --------- | | \< 1 000 swaps | \< 300 ms | | 10 000 swaps | \~700 ms | | 70 000 swaps (super-trader) | \~2 s | *** ### SDK Usage ```typescript theme={null} import { Mobula } from '@mobula/sdk'; const mobula = new Mobula({ apiKey: 'your-key' }); const history = await mobula.fetchWalletPositionsHistory({ wallet: '4sAUSQFdvWRBxR8UoLBYbw8CcXuwXWxnN8pXa4mtm5nU', sortBy: 'realizedPnl', order: 'desc', limit: 10, }); for (const { token, cycle } of history.data) { console.log(token.symbol, cycle.realizedPnlUSD); } ``` ### Use Cases * **Top-trades leaderboards**: surface a trader's best and worst closed positions. * **Backtest alpha**: evaluate how well a wallet recycles profits across different plays. * **Follow-the-whale**: watch which tokens a known trader is actually *closing* vs. still holding. ### Related Endpoints * [`/wallet/position-history`](wallet-position-history) — cycle-level history for a specific token. * [`/wallet/positions`](wallet-positions) — lifetime aggregate rows, one per token. ## OpenAPI ````yaml get /2/wallet/positions-history openapi: 3.0.0 info: version: 1.0.0 title: Mobula API description: >- Documentation of the Mobula API **Demo API**: The default server (demo-api.mobula.io) is a demo API with rate limits. For production use, please use api.mobula.io with an API key from https://admin.mobula.io servers: - url: https://demo-api.mobula.io/api/ description: Demo API (rate limited, for testing only) - url: https://api.mobula.io/api/ description: Production API (requires API key) security: [] tags: - name: V2 - Token description: Token details, price, security, ATH, and holder data - name: V2 - Market Data description: Market details, OHLCV history, and lighthouse metrics - name: V2 - Trades description: Token trades, enriched trades, and trade filters - name: V2 - Wallet description: Wallet positions, activity, trades, analysis, and labels - name: V2 - Assets description: Cross-chain asset details and price history - name: V2 - Swap description: Swap quoting and execution - name: V2 - Perps description: Perpetual futures quoting, execution, and positions - name: V2 - Bridge description: Cross-chain bridge quoting and intent status (Alpha Preview) - name: V2 - DeFi description: Bonding pools and pulse data - name: V2 - Search description: Universal fast search - name: V2 - Usage description: Per-key API and WebSocket usage history - name: V2 - Blockchains description: System metadata and chain listings - name: V2 - Prediction Markets description: >- Polymarket markets/events, wallet positions, and the full execution stack (auth, order build/submit/cancel, approvals, pUSD wrap/unwrap, deploy, deposit/withdraw, redeem). Alpha — see /api/2/pm/*. - name: V1 - Market Data description: Market prices, history, sparklines, pairs, and multi-data - name: V1 - Wallet description: Wallet portfolio, transactions, history, and NFTs - name: V1 - Token description: First buyers - name: V1 - Trades description: Market trades by pair - name: V1 - Metadata description: Token metadata, categories, and news - name: V1 - Assets description: List all assets - name: V1 - Search description: Search for assets, tokens, and pairs - name: V1 - DeFi description: Bonding pool pulse data - name: V1 - Blockchains description: Blockchain listings, pairs, and stats - name: V1 - Webhooks description: Webhook management - name: V1 - Feed description: Custom feed creation paths: /2/wallet/positions-history: get: tags: - V2 - Wallet summary: Get Wallet Positions History description: >- Alpha. Paginated list of every CLOSED position cycle the wallet has traded, across every token. Cycle semantics match `/wallet/position-history`. Currently open positions are excluded — use `/wallet/positions` for those. parameters: - schema: type: string description: Wallet address required: true description: Wallet address name: wallet in: query - schema: type: string description: >- Comma-separated list of chain IDs (e.g., "evm:1,solana:solana"). If omitted, all chains. required: false description: >- Comma-separated list of chain IDs (e.g., "evm:1,solana:solana"). If omitted, all chains. name: chainIds in: query - schema: type: number minimum: 1 maximum: 200 description: Number of closed positions per page (1-200, default 50) required: false description: Number of closed positions per page (1-200, default 50) name: limit in: query - schema: type: number nullable: true minimum: 0 description: Offset for pagination (default 0) required: false description: Offset for pagination (default 0) name: offset in: query - schema: type: string enum: - exitDate - realizedPnl - entryDate description: Sort field (default exitDate) required: false description: Sort field (default exitDate) name: sortBy in: query - schema: type: string enum: - asc - desc description: Sort order (default desc) required: false description: Sort order (default desc) name: order in: query responses: '200': description: Paginated closed-cycle history. content: application/json: schema: type: object properties: data: type: array items: type: object properties: token: type: object properties: address: type: string chainId: type: string symbol: type: string nullable: true name: type: string nullable: true decimals: type: number nullable: true default: 0 id: type: number nullable: true default: null priceUSD: type: number nullable: true default: 0 priceToken: type: number nullable: true default: 0 priceTokenString: type: string approximateReserveUSD: type: number nullable: true default: 0 approximateReserveTokenRaw: type: string approximateReserveToken: type: number nullable: true default: 0 totalSupply: type: number nullable: true default: 0 circulatingSupply: type: number nullable: true default: 0 marketCapUSD: type: number nullable: true default: 0 marketCapDilutedUSD: type: number nullable: true default: 0 logo: type: string nullable: true originLogoUrl: type: string nullable: true rank: type: number nullable: true default: null cexs: type: array items: type: string default: [] exchange: type: object properties: name: type: string logo: type: string required: - name - logo factory: type: string nullable: true source: type: string nullable: true sourceFactory: type: string nullable: true sourceMetadata: type: object nullable: true properties: name: type: string logo: type: string required: - name - logo sourceFactoryMetadata: type: object nullable: true properties: name: type: string logo: type: string required: - name - logo liquidityUSD: type: number nullable: true liquidityMaxUSD: type: number nullable: true bonded: type: boolean bondingPercentage: type: number nullable: true migrating: type: boolean bondingCurveAddress: type: string nullable: true preBondingFactory: type: string poolAddress: type: string blockchain: type: string type: type: string tokenType: type: string nullable: true enum: - '2020' - '2022' deployer: type: string nullable: true bondedAt: type: string nullable: true athUSD: type: number nullable: true atlUSD: type: number nullable: true athDate: type: string nullable: true atlDate: type: string nullable: true priceChange1minPercentage: type: number nullable: true default: 0 priceChange5minPercentage: type: number nullable: true default: 0 priceChange1hPercentage: type: number nullable: true default: 0 priceChange4hPercentage: type: number nullable: true default: 0 priceChange6hPercentage: type: number nullable: true default: 0 priceChange12hPercentage: type: number nullable: true default: 0 priceChange24hPercentage: type: number nullable: true default: 0 poolPriceChange1minPercentage: type: number nullable: true default: 0 poolPriceChange5minPercentage: type: number nullable: true default: 0 poolPriceChange1hPercentage: type: number nullable: true default: 0 poolPriceChange4hPercentage: type: number nullable: true default: 0 poolPriceChange6hPercentage: type: number nullable: true default: 0 poolPriceChange12hPercentage: type: number nullable: true default: 0 poolPriceChange24hPercentage: type: number nullable: true default: 0 liquidityBurnPercentage: type: number nullable: true volume1minUSD: type: number nullable: true default: 0 volume5minUSD: type: number nullable: true default: 0 volume15minUSD: type: number nullable: true default: 0 volume1hUSD: type: number nullable: true default: 0 volume4hUSD: type: number nullable: true default: 0 volume6hUSD: type: number nullable: true default: 0 volume12hUSD: type: number nullable: true default: 0 volume24hUSD: type: number nullable: true default: 0 volumeBuy1minUSD: type: number nullable: true default: 0 volumeBuy5minUSD: type: number nullable: true default: 0 volumeBuy15minUSD: type: number nullable: true default: 0 volumeBuy1hUSD: type: number nullable: true default: 0 volumeBuy4hUSD: type: number nullable: true default: 0 volumeBuy6hUSD: type: number nullable: true default: 0 volumeBuy12hUSD: type: number nullable: true default: 0 volumeBuy24hUSD: type: number nullable: true default: 0 volumeSell1minUSD: type: number nullable: true default: 0 volumeSell5minUSD: type: number nullable: true default: 0 volumeSell15minUSD: type: number nullable: true default: 0 volumeSell1hUSD: type: number nullable: true default: 0 volumeSell4hUSD: type: number nullable: true default: 0 volumeSell6hUSD: type: number nullable: true default: 0 volumeSell12hUSD: type: number nullable: true default: 0 volumeSell24hUSD: type: number nullable: true default: 0 trades1min: type: number nullable: true default: 0 trades5min: type: number nullable: true default: 0 trades15min: type: number nullable: true default: 0 trades1h: type: number nullable: true default: 0 trades4h: type: number nullable: true default: 0 trades6h: type: number nullable: true default: 0 trades12h: type: number nullable: true default: 0 trades24h: type: number nullable: true default: 0 buys1min: type: number nullable: true default: 0 buys5min: type: number nullable: true default: 0 buys15min: type: number nullable: true default: 0 buys1h: type: number nullable: true default: 0 buys4h: type: number nullable: true default: 0 buys6h: type: number nullable: true default: 0 buys12h: type: number nullable: true default: 0 buys24h: type: number nullable: true default: 0 sells1min: type: number nullable: true default: 0 sells5min: type: number nullable: true default: 0 sells15min: type: number nullable: true default: 0 sells1h: type: number nullable: true default: 0 sells4h: type: number nullable: true default: 0 sells6h: type: number nullable: true default: 0 sells12h: type: number nullable: true default: 0 sells24h: type: number nullable: true default: 0 buyers1min: type: number nullable: true default: 0 buyers5min: type: number nullable: true default: 0 buyers15min: type: number nullable: true default: 0 buyers1h: type: number nullable: true default: 0 buyers4h: type: number nullable: true default: 0 buyers6h: type: number nullable: true default: 0 buyers12h: type: number nullable: true default: 0 buyers24h: type: number nullable: true default: 0 sellers1min: type: number nullable: true default: 0 sellers5min: type: number nullable: true default: 0 sellers15min: type: number nullable: true default: 0 sellers1h: type: number nullable: true default: 0 sellers4h: type: number nullable: true default: 0 sellers6h: type: number nullable: true default: 0 sellers12h: type: number nullable: true default: 0 sellers24h: type: number nullable: true default: 0 traders1min: type: number nullable: true default: 0 traders5min: type: number nullable: true default: 0 traders15min: type: number nullable: true default: 0 traders1h: type: number nullable: true default: 0 traders4h: type: number nullable: true default: 0 traders6h: type: number nullable: true default: 0 traders12h: type: number nullable: true default: 0 traders24h: type: number nullable: true default: 0 feesPaid1minUSD: type: number nullable: true default: 0 feesPaid5minUSD: type: number nullable: true default: 0 feesPaid15minUSD: type: number nullable: true default: 0 feesPaid1hUSD: type: number nullable: true default: 0 feesPaid4hUSD: type: number nullable: true default: 0 feesPaid6hUSD: type: number nullable: true default: 0 feesPaid12hUSD: type: number nullable: true default: 0 feesPaid24hUSD: type: number nullable: true default: 0 totalFeesPaidUSD: type: number nullable: true default: 0 totalFeesPaidNativeRaw: type: string nullable: true default: '0' organicTrades1min: type: number nullable: true default: 0 organicTrades5min: type: number nullable: true default: 0 organicTrades15min: type: number nullable: true default: 0 organicTrades1h: type: number nullable: true default: 0 organicTrades4h: type: number nullable: true default: 0 organicTrades6h: type: number nullable: true default: 0 organicTrades12h: type: number nullable: true default: 0 organicTrades24h: type: number nullable: true default: 0 organicTraders1min: type: number nullable: true default: 0 organicTraders5min: type: number nullable: true default: 0 organicTraders15min: type: number nullable: true default: 0 organicTraders1h: type: number nullable: true default: 0 organicTraders4h: type: number nullable: true default: 0 organicTraders6h: type: number nullable: true default: 0 organicTraders12h: type: number nullable: true default: 0 organicTraders24h: type: number nullable: true default: 0 organicVolume1minUSD: type: number nullable: true default: 0 organicVolume5minUSD: type: number nullable: true default: 0 organicVolume15minUSD: type: number nullable: true default: 0 organicVolume1hUSD: type: number nullable: true default: 0 organicVolume4hUSD: type: number nullable: true default: 0 organicVolume6hUSD: type: number nullable: true default: 0 organicVolume12hUSD: type: number nullable: true default: 0 organicVolume24hUSD: type: number nullable: true default: 0 organicVolumeBuy1minUSD: type: number nullable: true default: 0 organicVolumeBuy5minUSD: type: number nullable: true default: 0 organicVolumeBuy15minUSD: type: number nullable: true default: 0 organicVolumeBuy1hUSD: type: number nullable: true default: 0 organicVolumeBuy4hUSD: type: number nullable: true default: 0 organicVolumeBuy6hUSD: type: number nullable: true default: 0 organicVolumeBuy12hUSD: type: number nullable: true default: 0 organicVolumeBuy24hUSD: type: number nullable: true default: 0 organicVolumeSell1minUSD: type: number nullable: true default: 0 organicVolumeSell5minUSD: type: number nullable: true default: 0 organicVolumeSell15minUSD: type: number nullable: true default: 0 organicVolumeSell1hUSD: type: number nullable: true default: 0 organicVolumeSell4hUSD: type: number nullable: true default: 0 organicVolumeSell6hUSD: type: number nullable: true default: 0 organicVolumeSell12hUSD: type: number nullable: true default: 0 organicVolumeSell24hUSD: type: number nullable: true default: 0 organicBuys1min: type: number nullable: true default: 0 organicBuys5min: type: number nullable: true default: 0 organicBuys15min: type: number nullable: true default: 0 organicBuys1h: type: number nullable: true default: 0 organicBuys4h: type: number nullable: true default: 0 organicBuys6h: type: number nullable: true default: 0 organicBuys12h: type: number nullable: true default: 0 organicBuys24h: type: number nullable: true default: 0 organicSells1min: type: number nullable: true default: 0 organicSells5min: type: number nullable: true default: 0 organicSells15min: type: number nullable: true default: 0 organicSells1h: type: number nullable: true default: 0 organicSells4h: type: number nullable: true default: 0 organicSells6h: type: number nullable: true default: 0 organicSells12h: type: number nullable: true default: 0 organicSells24h: type: number nullable: true default: 0 organicBuyers1min: type: number nullable: true default: 0 organicBuyers5min: type: number nullable: true default: 0 organicBuyers15min: type: number nullable: true default: 0 organicBuyers1h: type: number nullable: true default: 0 organicBuyers4h: type: number nullable: true default: 0 organicBuyers6h: type: number nullable: true default: 0 organicBuyers12h: type: number nullable: true default: 0 organicBuyers24h: type: number nullable: true default: 0 organicSellers1min: type: number nullable: true default: 0 organicSellers5min: type: number nullable: true default: 0 organicSellers15min: type: number nullable: true default: 0 organicSellers1h: type: number nullable: true default: 0 organicSellers4h: type: number nullable: true default: 0 organicSellers6h: type: number nullable: true default: 0 organicSellers12h: type: number nullable: true default: 0 organicSellers24h: type: number nullable: true default: 0 createdAt: type: string nullable: true latestTradeDate: type: string nullable: true holdersCount: type: number nullable: true description: type: string nullable: true socials: type: object properties: twitter: type: string nullable: true website: type: string nullable: true telegram: type: string nullable: true others: type: object nullable: true additionalProperties: nullable: true uri: type: string required: - twitter - website - telegram security: type: object nullable: true properties: buyTax: type: string nullable: true sellTax: type: string nullable: true transferPausable: type: boolean top10Holders: type: string isBlacklisted: type: boolean noMintAuthority: type: boolean isFreezable: type: boolean balanceMutable: type: boolean lowLiquidity: type: string burnRate: type: string liquidityBurnPercentage: type: number transferTax: type: string nullable: true isHoneypot: type: boolean isNotOpenSource: type: boolean renounced: type: boolean locked: type: string isWhitelisted: type: boolean isMintable: type: boolean modifyableTax: type: boolean selfDestruct: type: boolean twitterReusesCount: type: number nullable: true default: 0 twitterRenameCount: type: number nullable: true default: 0 twitterRenameHistory: type: array items: type: object properties: username: type: string lastChecked: type: string required: - username - lastChecked default: [] deployerMigrationsCount: type: number nullable: true default: 0 deployerTokensCount: type: number nullable: true default: 0 securityScore: type: number nullable: true default: null securityScoreUpdatedAt: type: string nullable: true default: null dexscreenerListed: type: boolean nullable: true default: false dexscreenerHeader: type: string nullable: true default: null dexscreenerAdPaid: type: boolean nullable: true default: false dexscreenerAdPaidDate: type: string nullable: true default: null dexScreenerEnhanced: type: object nullable: true properties: icon: type: string nullable: true header: type: string nullable: true description: type: string nullable: true links: type: array items: type: object properties: url: type: string label: type: string type: type: string required: - url default: [] isCto: type: boolean default: false timestamp: type: number nullable: true enhanced: type: boolean default: false previousEnhancements: type: array items: type: object properties: icon: type: string nullable: true header: type: string nullable: true description: type: string nullable: true links: type: array items: type: object properties: url: type: string label: type: string type: type: string required: - url default: [] isCto: type: boolean default: false timestamp: type: number nullable: true required: - icon - header - description - timestamp default: [] default: null required: - icon - header - description - timestamp dexscreenerPendingAt: type: string nullable: true default: null dexscreenerSocialPaid: type: boolean nullable: true default: false dexscreenerSocialPaidDate: type: string nullable: true default: null liveStatus: type: string nullable: true liveThumbnail: type: string nullable: true livestreamTitle: type: string nullable: true liveReplyCount: type: number nullable: true dexscreenerBoosted: type: boolean nullable: true default: false dexscreenerBoostedDate: type: string nullable: true default: null dexscreenerBoostedAmount: type: number nullable: true default: 0 trendingScore1min: type: number nullable: true default: 0 trendingScore5min: type: number nullable: true default: 0 trendingScore15min: type: number nullable: true default: 0 trendingScore1h: type: number nullable: true default: 0 trendingScore4h: type: number nullable: true default: 0 trendingScore6h: type: number nullable: true default: 0 trendingScore12h: type: number nullable: true default: 0 trendingScore24h: type: number nullable: true default: 0 surgeScore: type: number nullable: true default: null isMayhemMode: type: boolean nullable: true default: null isCashbackCoin: type: boolean nullable: true default: null isAgentMode: type: boolean nullable: true default: null isOGCoin: type: boolean nullable: true default: null top10HoldingsPercentage: type: number nullable: true top50HoldingsPercentage: type: number nullable: true top100HoldingsPercentage: type: number nullable: true top200HoldingsPercentage: type: number nullable: true devHoldingsPercentage: type: number nullable: true insidersHoldingsPercentage: type: number nullable: true bundlersHoldingsPercentage: type: number nullable: true snipersHoldingsPercentage: type: number nullable: true proTradersHoldingsPercentage: type: number nullable: true freshTradersHoldingsPercentage: type: number nullable: true smartTradersHoldingsPercentage: type: number nullable: true insidersCount: type: number nullable: true bundlersCount: type: number nullable: true snipersCount: type: number nullable: true freshTradersCount: type: number nullable: true proTradersCount: type: number nullable: true smartTradersCount: type: number nullable: true freshTradersBuys: type: number nullable: true proTradersBuys: type: number nullable: true smartTradersBuys: type: number nullable: true required: - address - chainId - symbol - name - priceTokenString - approximateReserveTokenRaw - logo - bondedAt - createdAt - latestTradeDate - description - socials - security - liveStatus - liveThumbnail - livestreamTitle - liveReplyCount cycle: type: object properties: isOpen: type: boolean entryDate: type: string nullable: true exitDate: type: string nullable: true buys: type: number sells: type: number volumeBuyToken: type: number volumeSellToken: type: number volumeBuyUSD: type: number volumeSellUSD: type: number avgBuyPriceUSD: type: number avgSellPriceUSD: type: number realizedPnlUSD: type: number unrealizedPnlUSD: type: number totalPnlUSD: type: number remainingBalance: type: number currentPriceUSD: type: number nullable: true feesUSD: type: number swapCount: type: number required: - isOpen - entryDate - exitDate - buys - sells - volumeBuyToken - volumeSellToken - volumeBuyUSD - volumeSellUSD - avgBuyPriceUSD - avgSellPriceUSD - realizedPnlUSD - unrealizedPnlUSD - totalPnlUSD - remainingBalance - currentPriceUSD - feesUSD - swapCount required: - token - cycle pagination: type: object properties: total: type: number page: type: number offset: type: number limit: type: number pageEntries: type: number required: - total - page - offset - limit - pageEntries required: - data - pagination ````