Skip to main content
GET
/
2
/
wallet
/
position-history
Get Wallet Position History
curl --request GET \
  --url https://demo-api.mobula.io/api/2/wallet/position-history
{
  "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
  },
  "cycles": [
    {
      "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
    }
  ]
}
Alpha — This endpoint is in early access. Response shape, field names, and cycle boundary semantics may change without notice.

​
What is a “cycle”?

Existing /wallet/position and /wallet/positions endpoints return the lifetime aggregate for a wallet+token pair (sum of all buys, sum of all sells, one blended avg price). That’s great for “what did I do overall”, but it hides the fact that most traders buy → fully sell → buy again → fully sell, and each of those is a distinct trade with its own PnL. A cycle is exactly that: a contiguous run of trades that opens on the first buy after a flat (zero-balance) state and closes when the cumulative token balance falls back to ≈ 0. Formally, a cycle is considered closed when the remaining balance ≤ 0.1% of the max balance reached within the cycle, so residual dust from rounding doesn’t keep cycles open forever. If the most recent cycle hasn’t closed yet, it’s returned with isOpen: true and a non-zero unrealizedPnlUSD computed from the wallet’s current remaining balance × the token’s live price.

​
Query Parameters

ParameterTypeRequiredDescription
walletstringYesWallet address.
assetstringYesToken contract address.
blockchainstringYesBlockchain name or chain ID (e.g. solana, ethereum, evm:8453).

​
Usage Example

curl -X GET "https://api.mobula.io/api/2/wallet/position-history?wallet=4sAUSQFdvWRBxR8UoLBYbw8CcXuwXWxnN8pXa4mtm5nU&asset=C1Ky45guR9upf281W8frfRVrqYLVaLLtVBGVugYkpump&blockchain=solana"

​
Sample Response

{
  "token": {
    "address": "C1Ky45guR9upf281W8frfRVrqYLVaLLtVBGVugYkpump",
    "chainId": "solana:solana",
    "symbol": "wumc",
    "name": "wumpus corp",
    "decimals": 6,
    "priceUSD": 0.00014,
    "logo": "https://...",
    "blockchain": "Solana"
    // ... full TokenDetailsOutput shape
  },
  "cycles": [
    {
      "isOpen": false,
      "entryDate": "2026-01-30T17:15:05.000Z",
      "exitDate": "2026-01-30T17:15:41.000Z",
      "buys": 2,
      "sells": 33,
      "volumeBuyToken": 104500000,
      "volumeSellToken": 104500000,
      "volumeBuyUSD": 2312.76,
      "volumeSellUSD": 15567.06,
      "avgBuyPriceUSD": 0.0000221,
      "avgSellPriceUSD": 0.000149,
      "realizedPnlUSD": 13254.30,
      "unrealizedPnlUSD": 0,
      "totalPnlUSD": 13254.30,
      "remainingBalance": 0,
      "currentPriceUSD": null,
      "feesUSD": 12.4,
      "swapCount": 35
    }
  ]
}
If the wallet is currently holding the token, the trailing cycle looks like this instead: 
{
  "isOpen": true,
  "entryDate": "2026-04-10T08:12:01.000Z",
  "exitDate": null,
  "buys": 5,
  "sells": 3,
  "volumeBuyToken": 21321141.12,
  "volumeSellToken": 10282806.53,
  "volumeBuyUSD": 3500.00,
  "volumeSellUSD": 2256.54,
  "avgBuyPriceUSD": 0.000164,
  "avgSellPriceUSD": 0.000219,
  "realizedPnlUSD": -1243.46,
  "unrealizedPnlUSD": -805.83,
  "totalPnlUSD": -2049.29,
  "remainingBalance": 11038334.58,
  "currentPriceUSD": 0.000124,
  "feesUSD": 8.1,
  "swapCount": 8
}

​
Field semantics

FieldMeaning
isOpentrue if the last cycle has not yet returned to dust balance.
entryDate / exitDateFirst and last swap in the cycle. exitDate is null when isOpen: true.
buys / sellsBuy and sell swap counts within this cycle only.
volumeBuyToken / volumeSellTokenCumulative token amounts bought / sold in the cycle.
volumeBuyUSD / volumeSellUSDCumulative USD value paid / received.
avgBuyPriceUSD / avgSellPriceUSDVolume-weighted average buy / sell unit price within the cycle.
realizedPnlUSD(avgSellPriceUSD − avgBuyPriceUSD) × min(volumeSellToken, volumeBuyToken). For a cleanly closed cycle this equals volumeSellUSD − volumeBuyUSD.
unrealizedPnlUSDOpen cycles only: remainingBalance × (currentPriceUSD − avgBuyPriceUSD). 0 for closed cycles.
totalPnlUSDrealizedPnlUSD + unrealizedPnlUSD.
remainingBalanceTokens still held at the cycle’s end. 0 for closed cycles (within dust tolerance).
currentPriceUSDLive unit price used to compute unrealizedPnlUSD. null for closed cycles.
feesUSDSum of gas + platform + mev fees paid across all swaps in the cycle.
swapCountTotal number of swaps that touched this cycle.
Orphaned sells that happen before any buy (for example, a token received via a raw transfer and later dumped) have no cost basis and are skipped — they cannot open a cycle.

​
SDK Usage

import { Mobula } from '@mobula/sdk';

const mobula = new Mobula({ apiKey: 'your-key' });

const history = await mobula.fetchWalletPositionHistory({
  wallet: '4sAUSQFdvWRBxR8UoLBYbw8CcXuwXWxnN8pXa4mtm5nU',
  asset: 'C1Ky45guR9upf281W8frfRVrqYLVaLLtVBGVugYkpump',
  blockchain: 'solana',
});

for (const cycle of history.cycles) {
  console.log(cycle.isOpen ? 'OPEN' : 'CLOSED', cycle.realizedPnlUSD);
}

Query Parameters

​
wallet
string
required

Wallet address

​
asset
string
required

Token contract address

​
chainId
string

Blockchain chain ID (e.g., "evm:56", "solana:solana")

Response

200 - application/json

Ordered list of position cycles for the wallet/token pair.

​
token
object
required
​
cycles
object[]
required