Skip to main content
GET
/
2
/
wallet
/
positions-history
Get Wallet Positions History
curl --request GET \
  --url https://demo-api.mobula.io/api/2/wallet/positions-history
{
  "data": [
    {
      "token": {
        "address": "<string>",
        "chainId": "<string>",
        "symbol": "<string>",
        "name": "<string>",
        "priceTokenString": "<string>",
        "approximateReserveTokenRaw": "<string>",
        "logo": "<string>",
        "bondedAt": "<string>",
        "createdAt": "<string>",
        "latestTradeDate": "<string>",
        "description": "<string>",
        "socials": {
          "twitter": "<string>",
          "website": "<string>",
          "telegram": "<string>",
          "others": {},
          "uri": "<string>"
        },
        "security": {
          "buyTax": "<string>",
          "sellTax": "<string>",
          "transferPausable": true,
          "top10Holders": "<string>",
          "isBlacklisted": true,
          "noMintAuthority": true,
          "balanceMutable": true,
          "lowLiquidity": "<string>",
          "burnRate": "<string>",
          "liquidityBurnPercentage": 123,
          "isHoneypot": true,
          "isNotOpenSource": true,
          "renounced": true,
          "locked": "<string>",
          "isWhitelisted": true,
          "isMintable": true,
          "modifyableTax": true,
          "selfDestruct": true
        },
        "liveStatus": "<string>",
        "liveThumbnail": "<string>",
        "livestreamTitle": "<string>",
        "liveReplyCount": 123,
        "decimals": 0,
        "id": null,
        "priceUSD": 0,
        "priceToken": 0,
        "approximateReserveUSD": 0,
        "approximateReserveToken": 0,
        "totalSupply": 0,
        "circulatingSupply": 0,
        "marketCapUSD": 0,
        "marketCapDilutedUSD": 0,
        "originLogoUrl": "<string>",
        "rank": null,
        "cexs": [],
        "exchange": {
          "name": "<string>",
          "logo": "<string>"
        },
        "factory": "<string>",
        "source": "<string>",
        "sourceFactory": "<string>",
        "sourceMetadata": {
          "name": "<string>",
          "logo": "<string>"
        },
        "sourceFactoryMetadata": {
          "name": "<string>",
          "logo": "<string>"
        },
        "liquidityUSD": 123,
        "liquidityMaxUSD": 123,
        "bonded": true,
        "bondingPercentage": 123,
        "bondingCurveAddress": "<string>",
        "preBondingFactory": "<string>",
        "poolAddress": "<string>",
        "blockchain": "<string>",
        "type": "<string>",
        "tokenType": "2020",
        "deployer": "<string>",
        "athUSD": 123,
        "atlUSD": 123,
        "athDate": "<string>",
        "atlDate": "<string>",
        "priceChange1minPercentage": 0,
        "priceChange5minPercentage": 0,
        "priceChange1hPercentage": 0,
        "priceChange4hPercentage": 0,
        "priceChange6hPercentage": 0,
        "priceChange12hPercentage": 0,
        "priceChange24hPercentage": 0,
        "poolPriceChange1minPercentage": 0,
        "poolPriceChange5minPercentage": 0,
        "poolPriceChange1hPercentage": 0,
        "poolPriceChange4hPercentage": 0,
        "poolPriceChange6hPercentage": 0,
        "poolPriceChange12hPercentage": 0,
        "poolPriceChange24hPercentage": 0,
        "liquidityBurnPercentage": 123,
        "volume1minUSD": 0,
        "volume5minUSD": 0,
        "volume15minUSD": 0,
        "volume1hUSD": 0,
        "volume4hUSD": 0,
        "volume6hUSD": 0,
        "volume12hUSD": 0,
        "volume24hUSD": 0,
        "volumeBuy1minUSD": 0,
        "volumeBuy5minUSD": 0,
        "volumeBuy15minUSD": 0,
        "volumeBuy1hUSD": 0,
        "volumeBuy4hUSD": 0,
        "volumeBuy6hUSD": 0,
        "volumeBuy12hUSD": 0,
        "volumeBuy24hUSD": 0,
        "volumeSell1minUSD": 0,
        "volumeSell5minUSD": 0,
        "volumeSell15minUSD": 0,
        "volumeSell1hUSD": 0,
        "volumeSell4hUSD": 0,
        "volumeSell6hUSD": 0,
        "volumeSell12hUSD": 0,
        "volumeSell24hUSD": 0,
        "trades1min": 0,
        "trades5min": 0,
        "trades15min": 0,
        "trades1h": 0,
        "trades4h": 0,
        "trades6h": 0,
        "trades12h": 0,
        "trades24h": 0,
        "buys1min": 0,
        "buys5min": 0,
        "buys15min": 0,
        "buys1h": 0,
        "buys4h": 0,
        "buys6h": 0,
        "buys12h": 0,
        "buys24h": 0,
        "sells1min": 0,
        "sells5min": 0,
        "sells15min": 0,
        "sells1h": 0,
        "sells4h": 0,
        "sells6h": 0,
        "sells12h": 0,
        "sells24h": 0,
        "buyers1min": 0,
        "buyers5min": 0,
        "buyers15min": 0,
        "buyers1h": 0,
        "buyers4h": 0,
        "buyers6h": 0,
        "buyers12h": 0,
        "buyers24h": 0,
        "sellers1min": 0,
        "sellers5min": 0,
        "sellers15min": 0,
        "sellers1h": 0,
        "sellers4h": 0,
        "sellers6h": 0,
        "sellers12h": 0,
        "sellers24h": 0,
        "traders1min": 0,
        "traders5min": 0,
        "traders15min": 0,
        "traders1h": 0,
        "traders4h": 0,
        "traders6h": 0,
        "traders12h": 0,
        "traders24h": 0,
        "feesPaid1minUSD": 0,
        "feesPaid5minUSD": 0,
        "feesPaid15minUSD": 0,
        "feesPaid1hUSD": 0,
        "feesPaid4hUSD": 0,
        "feesPaid6hUSD": 0,
        "feesPaid12hUSD": 0,
        "feesPaid24hUSD": 0,
        "totalFeesPaidUSD": 0,
        "totalFeesPaidNativeRaw": "0",
        "organicTrades1min": 0,
        "organicTrades5min": 0,
        "organicTrades15min": 0,
        "organicTrades1h": 0,
        "organicTrades4h": 0,
        "organicTrades6h": 0,
        "organicTrades12h": 0,
        "organicTrades24h": 0,
        "organicTraders1min": 0,
        "organicTraders5min": 0,
        "organicTraders15min": 0,
        "organicTraders1h": 0,
        "organicTraders4h": 0,
        "organicTraders6h": 0,
        "organicTraders12h": 0,
        "organicTraders24h": 0,
        "organicVolume1minUSD": 0,
        "organicVolume5minUSD": 0,
        "organicVolume15minUSD": 0,
        "organicVolume1hUSD": 0,
        "organicVolume4hUSD": 0,
        "organicVolume6hUSD": 0,
        "organicVolume12hUSD": 0,
        "organicVolume24hUSD": 0,
        "organicVolumeBuy1minUSD": 0,
        "organicVolumeBuy5minUSD": 0,
        "organicVolumeBuy15minUSD": 0,
        "organicVolumeBuy1hUSD": 0,
        "organicVolumeBuy4hUSD": 0,
        "organicVolumeBuy6hUSD": 0,
        "organicVolumeBuy12hUSD": 0,
        "organicVolumeBuy24hUSD": 0,
        "organicVolumeSell1minUSD": 0,
        "organicVolumeSell5minUSD": 0,
        "organicVolumeSell15minUSD": 0,
        "organicVolumeSell1hUSD": 0,
        "organicVolumeSell4hUSD": 0,
        "organicVolumeSell6hUSD": 0,
        "organicVolumeSell12hUSD": 0,
        "organicVolumeSell24hUSD": 0,
        "organicBuys1min": 0,
        "organicBuys5min": 0,
        "organicBuys15min": 0,
        "organicBuys1h": 0,
        "organicBuys4h": 0,
        "organicBuys6h": 0,
        "organicBuys12h": 0,
        "organicBuys24h": 0,
        "organicSells1min": 0,
        "organicSells5min": 0,
        "organicSells15min": 0,
        "organicSells1h": 0,
        "organicSells4h": 0,
        "organicSells6h": 0,
        "organicSells12h": 0,
        "organicSells24h": 0,
        "organicBuyers1min": 0,
        "organicBuyers5min": 0,
        "organicBuyers15min": 0,
        "organicBuyers1h": 0,
        "organicBuyers4h": 0,
        "organicBuyers6h": 0,
        "organicBuyers12h": 0,
        "organicBuyers24h": 0,
        "organicSellers1min": 0,
        "organicSellers5min": 0,
        "organicSellers15min": 0,
        "organicSellers1h": 0,
        "organicSellers4h": 0,
        "organicSellers6h": 0,
        "organicSellers12h": 0,
        "organicSellers24h": 0,
        "holdersCount": 123,
        "twitterReusesCount": 0,
        "twitterRenameCount": 0,
        "twitterRenameHistory": [],
        "deployerMigrationsCount": 0,
        "deployerTokensCount": 0,
        "dexscreenerListed": false,
        "dexscreenerHeader": null,
        "dexscreenerAdPaid": false,
        "dexscreenerAdPaidDate": null,
        "dexscreenerSocialPaid": false,
        "dexscreenerSocialPaidDate": null,
        "dexscreenerBoosted": false,
        "dexscreenerBoostedDate": null,
        "dexscreenerBoostedAmount": 0,
        "trendingScore1min": 0,
        "trendingScore5min": 0,
        "trendingScore15min": 0,
        "trendingScore1h": 0,
        "trendingScore4h": 0,
        "trendingScore6h": 0,
        "trendingScore12h": 0,
        "trendingScore24h": 0,
        "isMayhemMode": null,
        "isCashbackCoin": null,
        "isAgentMode": null,
        "top10HoldingsPercentage": 123,
        "top50HoldingsPercentage": 123,
        "top100HoldingsPercentage": 123,
        "top200HoldingsPercentage": 123,
        "devHoldingsPercentage": 123,
        "insidersHoldingsPercentage": 123,
        "bundlersHoldingsPercentage": 123,
        "snipersHoldingsPercentage": 123,
        "proTradersHoldingsPercentage": 123,
        "freshTradersHoldingsPercentage": 123,
        "smartTradersHoldingsPercentage": 123,
        "insidersCount": 123,
        "bundlersCount": 123,
        "snipersCount": 123,
        "freshTradersCount": 123,
        "proTradersCount": 123,
        "smartTradersCount": 123,
        "freshTradersBuys": 123,
        "proTradersBuys": 123,
        "smartTradersBuys": 123
      },
      "cycle": {
        "isOpen": true,
        "entryDate": "<string>",
        "exitDate": "<string>",
        "buys": 123,
        "sells": 123,
        "volumeBuyToken": 123,
        "volumeSellToken": 123,
        "volumeBuyUSD": 123,
        "volumeSellUSD": 123,
        "avgBuyPriceUSD": 123,
        "avgSellPriceUSD": 123,
        "realizedPnlUSD": 123,
        "unrealizedPnlUSD": 123,
        "totalPnlUSD": 123,
        "remainingBalance": 123,
        "currentPriceUSD": 123,
        "feesUSD": 123,
        "swapCount": 123
      }
    }
  ],
  "pagination": {
    "total": 123,
    "page": 123,
    "offset": 123,
    "limit": 123,
    "pageEntries": 123
  }
}
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 or /wallet/position-history to see them.

​
Query Parameters

ParameterTypeRequiredDescription
walletstringYesWallet address.
chainIdsstringNoComma-separated list of chain IDs (e.g. evm:1,solana:solana). If omitted, all chains.
limitnumberNoPage size. 1–200, default 50.
offsetnumberNoPagination offset, default 0.
sortBystringNoOne of exitDate (default), entryDate, realizedPnl.
orderstringNoasc or desc (default).

​
Usage Examples

Top 10 most-profitable closed trades: 
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: 
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

{
  "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. 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 sizeLatency
< 1 000 swaps< 300 ms
10 000 swaps~700 ms
70 000 swaps (super-trader)~2 s

​
SDK Usage

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.

Query Parameters

​
wallet
string
required

Wallet address

​
chainIds
string

Comma-separated list of chain IDs (e.g., "evm:1,solana:solana"). If omitted, all chains.

​
limit
number

Number of closed positions per page (1-200, default 50)

Required range: 1 <= x <= 200
​
offset
number | null

Offset for pagination (default 0)

Required range: x >= 0
​
sortBy
enum<string>

Sort field (default exitDate)

Available options:
exitDate,
realizedPnl,
entryDate
​
order
enum<string>

Sort order (default desc)

Available options:
asc,
desc

Response

200 - application/json

Paginated closed-cycle history.

​
data
object[]
required
​
pagination
object
required