> ## 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.
# Curated Data Model
### Swap model
Swaps are abstractions on AMM transfers, procotol & chain agnostic.
Identifier on Mobula: `swap`
**Note on Swap Direction and Amount Signs:**\
In a swap, tokens move between `addressToken0` and `addressToken1`. The direction of the swap and the meaning of the amounts can be understood as follows:
* If `amount0` is **positive**, the token at `addressToken0` is **going into the pool**, and it is being swapped **for the token at `addressToken1`**.
* If `amount0` is **negative**, the token at `addressToken0` is **coming out of the pool**, meaning the swap is **from `addressToken1` to `addressToken0`**.
The `amount1` value reflects the opposite movement:
* Positive → token enters the pool
* Negative → token leaves the pool
**In simple terms:**
* Positive `amount0` → swapping **Token0 → Token1**
* Negative `amount0` → swapping **Token1 → Token0**
**Example: SOL → SUPER Agent Swap:**
```json theme={null}
{
"ratio": 1608943.9743539998,
"swapSenderAddress": "CxNUEf6Aw8o8i84GfyPE3ZcKKpa4XRyuXEwypECbdjV8",
"poolAddress": "EQ4p8CGFJz92FkL8H4eeN3txR1ohp613ZWdVkjFromED",
"rawAmount0": "1000000000",
"rawAmount1": "-1608943974354",
"poolType": "raydium",
"swapType": "REGULAR",
"addressToken0": "So11111111111111111111111111111111111111112", //SOL
"addressToken1": "GqwD19dg25154kJ8kK2FLCeXZJzPDs6CPaUhdsW9pump", //SuperAgent
"blockHeight": "1737653025",
"transactionHash": "3QbHFowf7xeW9BM2fR2TKfYcmUKNnhQN7XyqdEmqS3SWKtfEw686RDxKaFxp3dGGc7D1RZuHaCrzSJEkg3hn9s5A",
"transactionSenderAddress": "CxNUEf6Aw8o8i84GfyPE3ZcKKpa4XRyuXEwypECbdjV8",
"transactionIndex": 0,
"blockHash": "GMKNhiUnUVQrTzYuy2t5qZVd1JfoyGi5LdifNG6gEHiP",
"logIndex": 0,
"chainId": "solana:solana",
"timestamp": "1737653025",
"date": "2025-01-23T17:23:45.000Z",
"priceUSDToken0": 250.0741553570125,
"priceUSDToken1": 0.00015542750980960583,
"amount0": 1, // Positive → Token0 goes into the pool
"amount1": -1608943.974354, // Negative → Token1 comes out of the pool
"amountUSD": 250.0741553570125,
"type": "swap"
}
```
### Enriched Swap model
The Enriched Swap extends the basic Swap model with `baseTokenData`, `post & pre balances`, `baseToken` and `quoteToken` identification, and `derived fields` for UI and analytics.
**Important**: The `baseTokenData` field contains enriched data (including price, volume, market cap, liquidity, and many other stats) for the base token as determined by baseQuote logic.
```json theme={null}
{
"ratio": 9202655.68008125,
"swapSenderAddress": "7rhFTmUrRSQsL2b3YDoTuSC2sBQUeN9smbSHpne3vowa",
"poolAddress": "4WYhS4JwJQsqfVfNx2uN9ZoRhrMTTsYo8kjdTLvFtSDy",
"rawAmount0": "320000000",
"rawAmount1": "-2944849817626",
"poolType": "raydium-clmm",
"swapType": "REGULAR",
"rawPostBalance0": "0",
"rawPostBalance1": "52076639903895",
"rawPreBalance0": "0",
"rawPreBalance1": "49131790086269",
"addressToken0": "So11111111111111111111111111111111111111112",
"addressToken1": "HjgFP3f1nc9kxD71YQXxD1fWHZLNp6b5ARdvhfVKpgCP",
"blockHeight": "370511250",
"transactionHash": "snFJGsc6gUyZHpYTbxVQQnDYpWSuPUJ4NTdvTJHTX6Wyd2Amsb3MTbNeyDe9VzkRVf87DhQ1aV79Ptnq2fZufei",
"transactionSenderAddress": "7rhFTmUrRSQsL2b3YDoTuSC2sBQUeN9smbSHpne3vowa",
"transactionIndex": 1007,
"blockHash": "snFJGsc6gUyZHpYTbxVQQnDYpWSuPUJ4NTdvTJHTX6Wyd2Amsb3MTbNeyDe9VzkRVf87DhQ1aV79Ptnq2fZufei",
"miniBlockSlot": 3705112501007,
"logIndex": 0,
"chainId": "solana:solana",
"timestamp": "1759334642100",
"date": "2025-10-01T16:04:02.100Z",
"priceUSDToken0": 220.4363745057309,
"priceUSDToken1": 0.000023953561033784614,
"amount0": 0.32,
"amount1": -2944849.817626,
"amountUSD": 70.53963984183389,
"gasFeesUSD": 0.0001254,
"platformFeesUSD": 0.0002,
"mevFeesUSD": 0.0005,
"totalFeesUSD": 0.0008454,
"baseToken": "HjgFP3f1nc9kxD71YQXxD1fWHZLNp6b5ARdvhfVKpgCP",
"quoteToken": "So11111111111111111111111111111111111111112",
"pair": "4WYhS4JwJQsqfVfNx2uN9ZoRhrMTTsYo8kjdTLvFtSDy",
"tokenPrice": 0.000023953561033784614,
"tokenPriceVs": 220.4363745057309,
"tokenAmount": 2944849.817626,
"tokenAmountVs": 0.32,
"tokenAmountUsd": 70.53963984183389,
"type": "buy",
"operation": "regular",
"blockchain": "Solana",
"hash": "snFJGsc6gUyZHpYTbxVQQnDYpWSuPUJ4NTdvTJHTX6Wyd2Amsb3MTbNeyDe9VzkRVf87DhQ1aV79Ptnq2fZufei",
"sender": "7rhFTmUrRSQsL2b3YDoTuSC2sBQUeN9smbSHpne3vowa",
"tokenAmountRaw": 2944849817626,
"tokenAmountRawVs": "320000000",
"baseTokenData": {
"chainId": "solana:solana",
"address": "HjgFP3f1nc9kxD71YQXxD1fWHZLNp6b5ARdvhfVKpgCP",
"name": "🦊",
"symbol": "🦊",
"decimals": 6,
"priceUSD": 0.000023953561033784614,
"volume24hUSD": 150000,
"liquidityUSD": 50000,
"marketCapUSD": 239535,
"priceChange24hPercentage": 5.2,
"id": 12345,
"logo": "https://pbs.twimg.com/media/G1ViqBdbQAA0-nS?format=jpg&name=360x360",
"deployer": "7rhFTmUrRSQsL2b3YDoTuSC2sBQUeN9smbSHpne3vowa",
"source": "raydium",
"totalSupply": "10000000000",
"circulatingSupply": "10000000000"
},
"position": {
"balance": 2944849.817626,
"rawBalance": "2944849817626",
"amountUSD": 70.54,
"nativeBalanceRaw": "92553887",
"nativeBalance": 0.092553887,
"buys": 1,
"sells": 0,
"volumeBuyToken": 2944849.817626,
"volumeSellToken": 0,
"volumeBuy": 70.54,
"volumeSell": 0,
"avgBuyPriceUSD": 0.000023953561033784614,
"avgSellPriceUSD": 0,
"realizedPnlUSD": 0,
"unrealizedPnlUSD": 0,
"totalPnlUSD": 0,
"realizedPnlPercent": 0,
"unrealizedPnlPercent": 0
}
},
```
### Position data on Enriched Swaps
Every `swap-enriched` event includes a `position` object that tracks the swap sender's (or recipient's) running position for the base token. This is computed in real-time from on-chain data and historical trades.
| Field | Type | Description |
| ---------------------- | -------- | ------------------------------------------------------------- |
| `balance` | `number` | Current token balance (human-readable) |
| `rawBalance` | `string` | Token balance as raw string (unformatted) |
| `amountUSD` | `number` | Token balance value in USD (balance × currentPrice) |
| `nativeBalanceRaw` | `string` | Native chain token balance in lamports/wei |
| `nativeBalance` | `number` | Native chain token balance (formatted, e.g. SOL not lamports) |
| `buys` | `number` | Total number of buy transactions |
| `sells` | `number` | Total number of sell transactions |
| `volumeBuyToken` | `number` | Total tokens bought |
| `volumeSellToken` | `number` | Total tokens sold |
| `volumeBuy` | `number` | Total USD value of buys |
| `volumeSell` | `number` | Total USD value of sells |
| `avgBuyPriceUSD` | `number` | Average buy price in USD |
| `avgSellPriceUSD` | `number` | Average sell price in USD |
| `realizedPnlUSD` | `number` | Realized profit/loss in USD |
| `unrealizedPnlUSD` | `number` | Unrealized profit/loss in USD |
| `totalPnlUSD` | `number` | Total P\&L (realized + unrealized) |
| `realizedPnlPercent` | `number` | Realized PnL as percentage of cost basis |
| `unrealizedPnlPercent` | `number` | Unrealized PnL as percentage of cost basis |
### Pool model
Pools are abstractions on AMM pools, protocol & chain agnostic.
Identifier on Mobula: `pool`
Example:
```json theme={null}
{
"chainId": "solana:solana",
"address": "B945wuhaQz3p238XDnghSsLKix8MiizT2j2yuHSgX7Xi",
"type": "pool",
"factory": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
"tokens": [
"So11111111111111111111111111111111111111112",
"C8U4ofzDkFdwxxP9twNut4vkxVVSQovHDedGAQ5apump"
],
"createdAt": 1744358732000,
"deployer": "BjMRkgnfkDPVPjLJqejEV5dhrnVNJ4ycriMp3ctcqYME",
"source": "pumpfun"
}
```