Get Wallet Holdings

GET /api/2/wallet/holdings
POST /api/2/wallet/holdings

curl "https://genius-api.mobula.io/api/2/wallet/holdings?wallet=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&blockchains=ethereum,base&minLiquidity=10000" \
  -H "Authorization: YOUR_API_KEY"

interface WalletHoldingsPostBody extends WalletHoldingsQueryParams {
  filters?: WalletHoldingFilters;
}

interface WalletHoldingsQueryParams {
  wallet?: string | number | boolean;
  wallets?: string | number | boolean;
  portfolio?: string | number | boolean;
  blockchains?: string | number | boolean;
  asset?: string | number | boolean;
  unlistedAssets?: string | number | boolean;
  filterSpam?: string | number | boolean;
  minLiquidity?: string | number | boolean;
  fetchAllChains?: string | number | boolean;
  fetchEmptyBalances?: string | number | boolean;
  backfillTransfers?: string | number | boolean;
  pnl?: string | number | boolean;
  from?: string | number | boolean;
  to?: string | number | boolean;
  period?: string | number | boolean;
  accuracy?: string | number | boolean;
  testnet?: string | number | boolean;
}

type WalletHoldingFilters = {
  OR?: WalletHoldingFilters[];
  AND?: WalletHoldingFilters[];
  NOT?: WalletHoldingFilters | WalletHoldingFilters[];
  [tokenField: string]:
    | FilterValue
    | WalletHoldingFilters
    | WalletHoldingFilters[]
    | undefined;
};

type FilterValue = FilterOperator | string | number | boolean | null;

interface FilterOperator<T = unknown> {
  equals?: T | null;
  not?: T | null | FilterOperator<T>;
  in?: T[];
  notIn?: T[];
  gte?: number;
  lte?: number;
  gt?: number;
  lt?: number;
  contains?: string;
  startsWith?: string;
  endsWith?: string;
  isNull?: boolean;
  isNotNull?: boolean;
}

{
  "filters": {
    "security.isHoneypot": false,
    "socials.website": { "isNotNull": true }
  }
}

{
  "filters": {
    "security": {
      "isHoneypot": false,
      "isMintable": false
    },
    "socials": {
      "website": { "isNotNull": true }
    }
  }
}

{
  "filters": {
    "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "chainId": { "in": ["evm:1", "evm:8453", "solana:solana"] },
    "symbol": { "notIn": ["SCAM", "TEST"] },
    "name": { "contains": "wrapped" },
    "decimals": { "equals": 18 },

    "priceUSD": { "gte": 0.01, "lte": 10000 },
    "liquidityUSD": { "gte": 100000 },
    "liquidityMaxUSD": { "gte": 250000 },
    "marketCapUSD": { "gte": 1000000 },
    "marketCapDilutedUSD": { "lte": 50000000 },
    "totalSupply": { "gt": 0 },
    "circulatingSupply": { "gt": 0 },

    "priceChange1hPercentage": { "gt": 0 },
    "priceChange24hPercentage": { "gte": 5 },
    "poolPriceChange24hPercentage": { "lt": 50 },

    "volume1hUSD": { "gte": 10000 },
    "volume24hUSD": { "gte": 500000 },
    "volumeBuy24hUSD": { "gte": 250000 },
    "volumeSell24hUSD": { "lte": 250000 },

    "trades24h": { "gte": 100 },
    "buys24h": { "gte": 50 },
    "sells24h": { "gte": 10 },
    "buyers24h": { "gte": 25 },
    "sellers24h": { "gte": 10 },
    "traders24h": { "gte": 30 },

    "feesPaid24hUSD": { "gte": 100 },
    "totalFeesPaidUSD": { "gte": 1000 },
    "organicTrades24h": { "gte": 25 },
    "organicVolume24hUSD": { "gte": 100000 },
    "organicBuyers24h": { "gte": 10 },

    "holdersCount": { "gte": 500 },
    "top10HoldingsPercentage": { "lte": 30 },
    "devHoldingsPercentage": { "lte": 5 },
    "insidersHoldingsPercentage": { "lte": 10 },
    "bundlersCount": { "lte": 3 },
    "smartTradersCount": { "gte": 5 },

    "security.isHoneypot": false,
    "security.isBlacklisted": false,
    "security.isMintable": false,
    "security.noMintAuthority": true,
    "security.isFreezable": false,

    "socials.website": { "isNotNull": true },
    "socials.twitter": { "isNotNull": true },
    "description": { "contains": "liquid" },
    "logo": { "isNotNull": true },

    "source": { "in": ["pumpfun", "raydium", "uniswap-v2"] },
    "factory": { "isNotNull": true },
    "poolAddress": { "isNotNull": true },
    "bonded": true,
    "migrating": false,
    "bondingPercentage": { "gte": 90 },
    "deployer": { "not": null },

    "dexscreenerListed": true,
    "dexscreenerAdPaid": false,
    "liveStatus": { "not": null },
    "trendingScore24h": { "gte": 10 },
    "surgeScore": { "gte": 5 },
    "isMayhemMode": false,
    "isCashbackCoin": false,
    "isAgentMode": false,
    "isOGCoin": false
  }
}

curl -X POST "https://genius-api.mobula.io/api/2/wallet/holdings" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "blockchains": "ethereum,base,solana",
    "minLiquidity": 10000,
    "filters": {
      "AND": [
        { "marketCapUSD": { "gte": 1000000 } },
        { "liquidityUSD": { "gte": 100000 } },
        { "security.isHoneypot": false },
        { "security.isMintable": false },
        { "socials.website": { "isNotNull": true } }
      ],
      "NOT": [
        { "symbol": { "contains": "test" } },
        { "name": { "contains": "airdrop" } }
      ]
    }
  }'

curl -X POST "https://genius-api.mobula.io/api/2/wallet/holdings" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallets": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045,0x00000000219ab540356cBB839Cbe05303d7705Fa",
    "blockchains": "ethereum,base",
    "filters": {
      "OR": [
        {
          "AND": [
            { "symbol": { "in": ["WETH", "USDC"] } },
            { "liquidityUSD": { "gte": 1000000 } }
          ]
        },
        {
          "AND": [
            { "priceChange24hPercentage": { "gt": 10 } },
            { "volume24hUSD": { "gte": 500000 } },
            { "security": { "isHoneypot": false } }
          ]
        }
      ]
    }
  }'

interface WalletHoldingsResponse {
  data: WalletHoldingsOutput;
  backfillStatus?: 'processed' | 'processing' | 'pending';
}

interface WalletHoldingsOutput {
  totalWalletBalanceUSD: number;
  wallets: string[];
  holdings: WalletHolding[];
  holdingsCount: number;
  balancesLength: number;
}

interface WalletHolding {
  token: WalletHoldingToken;
  amount: number;
  amountRaw?: string | null;
  amountUSD: number;
  allocation: number;
  chainBalances: Record<string, WalletHoldingChainBalance>;
  wallets: string[];
}

interface WalletHoldingChainBalance {
  chainId: string;
  address: string;
  amount: number;
  amountRaw: string;
  amountUSD: number;
  priceUSD?: number | null;
  liquidityUSD?: number | null;
  decimals: number;
  tokenType?: '2020' | '2022' | 'erc20' | 'trc10' | 'trc20' | null;
  security?: SecurityFlags | null;
  wallets: Record<string, WalletChainWalletBalance>;
}

interface WalletChainWalletBalance {
  amount: number;
  amountRaw: string;
  amountUSD: number;
  lamports?: string | null;
  tokenAccount?: string | null;
}

interface WalletHoldingToken extends HolderStats {
  address: string;
  chainId: string;
  symbol: string | null;
  name: string | null;
  decimals: number;
  id?: number | null;

  priceUSD: number;
  priceToken: number;
  priceTokenString: string;
  approximateReserveUSD: number;
  approximateReserveTokenRaw: string;
  approximateReserveToken: number;
  totalSupply: number;
  circulatingSupply: number;
  marketCapUSD: number;
  marketCapDilutedUSD: number;
  logo: string | null;
  originLogoUrl?: string | null;
  rank: number | null;
  cexs: string[];

  exchange?: {
    name: string;
    logo: string;
  };

  factory?: string | null;
  source?: string | null;
  sourceFactory?: string | null;
  sourceMetadata?: MetadataSource | null;
  sourceFactoryMetadata?: MetadataSource | null;

  liquidityUSD?: number;
  liquidityMaxUSD?: number;
  bonded?: boolean;
  bondingPercentage?: number;
  migrating?: boolean;
  bondingCurveAddress?: string | null;
  preBondingFactory?: string;
  poolAddress?: string;

  blockchain?: string;
  type?: string;
  tokenType: '2020' | '2022' | 'erc20' | 'trc10' | 'trc20' | null;

  deployer?: string | null;
  bondedAt: string | null;
  athUSD?: number;
  atlUSD?: number;
  athDate?: string;
  atlDate?: string;

  priceChange1minPercentage: number;
  priceChange5minPercentage: number;
  priceChange1hPercentage: number;
  priceChange4hPercentage: number;
  priceChange6hPercentage: number;
  priceChange12hPercentage: number;
  priceChange24hPercentage: number;

  poolPriceChange1minPercentage: number;
  poolPriceChange5minPercentage: number;
  poolPriceChange1hPercentage: number;
  poolPriceChange4hPercentage: number;
  poolPriceChange6hPercentage: number;
  poolPriceChange12hPercentage: number;
  poolPriceChange24hPercentage: number;

  liquidityBurnPercentage?: number | null;

  volume1minUSD: number;
  volume5minUSD: number;
  volume15minUSD: number;
  volume1hUSD: number;
  volume4hUSD: number;
  volume6hUSD: number;
  volume12hUSD: number;
  volume24hUSD: number;

  volumeBuy1minUSD: number;
  volumeBuy5minUSD: number;
  volumeBuy15minUSD: number;
  volumeBuy1hUSD: number;
  volumeBuy4hUSD: number;
  volumeBuy6hUSD: number;
  volumeBuy12hUSD: number;
  volumeBuy24hUSD: number;

  volumeSell1minUSD: number;
  volumeSell5minUSD: number;
  volumeSell15minUSD: number;
  volumeSell1hUSD: number;
  volumeSell4hUSD: number;
  volumeSell6hUSD: number;
  volumeSell12hUSD: number;
  volumeSell24hUSD: number;

  trades1min: number;
  trades5min: number;
  trades15min: number;
  trades1h: number;
  trades4h: number;
  trades6h: number;
  trades12h: number;
  trades24h: number;

  buys1min: number;
  buys5min: number;
  buys15min: number;
  buys1h: number;
  buys4h: number;
  buys6h: number;
  buys12h: number;
  buys24h: number;

  sells1min: number;
  sells5min: number;
  sells15min: number;
  sells1h: number;
  sells4h: number;
  sells6h: number;
  sells12h: number;
  sells24h: number;

  buyers1min: number;
  buyers5min: number;
  buyers15min: number;
  buyers1h: number;
  buyers4h: number;
  buyers6h: number;
  buyers12h: number;
  buyers24h: number;

  sellers1min: number;
  sellers5min: number;
  sellers15min: number;
  sellers1h: number;
  sellers4h: number;
  sellers6h: number;
  sellers12h: number;
  sellers24h: number;

  traders1min: number;
  traders5min: number;
  traders15min: number;
  traders1h: number;
  traders4h: number;
  traders6h: number;
  traders12h: number;
  traders24h: number;

  feesPaid1minUSD: number;
  feesPaid5minUSD: number;
  feesPaid15minUSD: number;
  feesPaid1hUSD: number;
  feesPaid4hUSD: number;
  feesPaid6hUSD: number;
  feesPaid12hUSD: number;
  feesPaid24hUSD: number;
  totalFeesPaidUSD: number;
  totalFeesPaidNativeRaw: string;

  organicTrades1min: number;
  organicTrades5min: number;
  organicTrades15min: number;
  organicTrades1h: number;
  organicTrades4h: number;
  organicTrades6h: number;
  organicTrades12h: number;
  organicTrades24h: number;

  organicTraders1min: number;
  organicTraders5min: number;
  organicTraders15min: number;
  organicTraders1h: number;
  organicTraders4h: number;
  organicTraders6h: number;
  organicTraders12h: number;
  organicTraders24h: number;

  organicVolume1minUSD: number;
  organicVolume5minUSD: number;
  organicVolume15minUSD: number;
  organicVolume1hUSD: number;
  organicVolume4hUSD: number;
  organicVolume6hUSD: number;
  organicVolume12hUSD: number;
  organicVolume24hUSD: number;

  organicVolumeBuy1minUSD: number;
  organicVolumeBuy5minUSD: number;
  organicVolumeBuy15minUSD: number;
  organicVolumeBuy1hUSD: number;
  organicVolumeBuy4hUSD: number;
  organicVolumeBuy6hUSD: number;
  organicVolumeBuy12hUSD: number;
  organicVolumeBuy24hUSD: number;

  organicVolumeSell1minUSD: number;
  organicVolumeSell5minUSD: number;
  organicVolumeSell15minUSD: number;
  organicVolumeSell1hUSD: number;
  organicVolumeSell4hUSD: number;
  organicVolumeSell6hUSD: number;
  organicVolumeSell12hUSD: number;
  organicVolumeSell24hUSD: number;

  organicBuys1min: number;
  organicBuys5min: number;
  organicBuys15min: number;
  organicBuys1h: number;
  organicBuys4h: number;
  organicBuys6h: number;
  organicBuys12h: number;
  organicBuys24h: number;

  organicSells1min: number;
  organicSells5min: number;
  organicSells15min: number;
  organicSells1h: number;
  organicSells4h: number;
  organicSells6h: number;
  organicSells12h: number;
  organicSells24h: number;

  organicBuyers1min: number;
  organicBuyers5min: number;
  organicBuyers15min: number;
  organicBuyers1h: number;
  organicBuyers4h: number;
  organicBuyers6h: number;
  organicBuyers12h: number;
  organicBuyers24h: number;

  organicSellers1min: number;
  organicSellers5min: number;
  organicSellers15min: number;
  organicSellers1h: number;
  organicSellers4h: number;
  organicSellers6h: number;
  organicSellers12h: number;
  organicSellers24h: number;

  createdAt: string | null;
  latestTradeDate: string | null;
  holdersCount?: number | null;
  description: string | null;
  socials: {
    twitter: string | null;
    website: string | null;
    telegram: string | null;
    others?: Record<string, unknown> | null;
    uri?: string;
  };
  security: SecurityFlags | null;

  twitterReusesCount: number | null;
  twitterRenameCount: number;
  twitterRenameHistory: Array<{
    username: string;
    lastChecked: string;
  }>;

  deployerMigrationsCount: number;
  deployerTokensCount: number;
  securityScore: number | null;
  securityScoreUpdatedAt: string | null;

  dexscreenerListed: boolean | null;
  dexscreenerHeader: string | null;
  dexscreenerAdPaid: boolean | null;
  dexscreenerAdPaidDate: string | null;
  dexScreenerEnhanced: Record<string, unknown> | null;
  dexscreenerPendingAt: string | null;
  dexscreenerSocialPaid: boolean | null;
  dexscreenerSocialPaidDate: string | null;

  liveStatus: string | null;
  liveThumbnail: string | null;
  livestreamTitle: string | null;
  liveReplyCount: number | null;
  dexscreenerBoosted: boolean | null;
  dexscreenerBoostedDate: string | null;
  dexscreenerBoostedAmount: number | null;

  trendingScore1min: number;
  trendingScore5min: number;
  trendingScore15min: number;
  trendingScore1h: number;
  trendingScore4h: number;
  trendingScore6h: number;
  trendingScore12h: number;
  trendingScore24h: number;

  surgeScore: number | null;
  isMayhemMode: boolean | null;
  isCashbackCoin: boolean | null;
  isAgentMode: boolean | null;
  isOGCoin: boolean | null;
}

interface MetadataSource {
  name: string;
  logo: string;
}

interface HolderStats {
  holdersCount?: number | null;
  top10HoldingsPercentage?: number | null;
  top50HoldingsPercentage?: number | null;
  top100HoldingsPercentage?: number | null;
  top200HoldingsPercentage?: number | null;
  devHoldingsPercentage?: number | null;
  insidersHoldingsPercentage?: number | null;
  bundlersHoldingsPercentage?: number | null;
  snipersHoldingsPercentage?: number | null;
  proTradersHoldingsPercentage?: number | null;
  freshTradersHoldingsPercentage?: number | null;
  smartTradersHoldingsPercentage?: number | null;
  insidersCount?: number | null;
  bundlersCount?: number | null;
  snipersCount?: number | null;
  freshTradersCount?: number | null;
  proTradersCount?: number | null;
  smartTradersCount?: number | null;
  freshTradersBuys?: number | null;
  proTradersBuys?: number | null;
  smartTradersBuys?: number | null;
}

interface SecurityFlags {
  buyTax?: string;
  sellTax?: string;
  transferTax?: string;
  transferPausable?: boolean;
  top10Holders?: string;
  isBlacklisted?: boolean;
  isHoneypot?: boolean;
  isNotOpenSource?: boolean;
  renounced?: boolean;
  locked?: string;
  isWhitelisted?: boolean;
  balanceMutable?: boolean;
  lowLiquidity?: string;
  burnRate?: string;
  isMintable?: boolean;
  modifyableTax?: boolean;
  selfDestruct?: boolean;
  liquidityBurnPercentage?: number;
  noMintAuthority?: boolean;
  isFreezable?: boolean;
  frozen?: boolean;
}

{
  "data": {
    "totalWalletBalanceUSD": 5234.22,
    "wallets": [
      "0xwalletA",
      "0xwalletB"
    ],
    "holdingsCount": 1,
    "balancesLength": 1,
    "holdings": [
      {
        "token": {
          "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "chainId": "evm:1",
          "symbol": "USDC",
          "name": "USD Coin",
          "decimals": 6,
          "id": 100004304,
          "priceUSD": 1,
          "liquidityUSD": 250000000,
          "security": {
            "isHoneypot": false,
            "isMintable": false
          }
        },
        "amount": 1250,
        "amountUSD": 1250,
        "allocation": 23.88,
        "wallets": [
          "0xwalletA",
          "0xwalletB"
        ],
        "chainBalances": {
          "evm:1": {
            "chainId": "evm:1",
            "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "amount": 800,
            "amountRaw": "800000000",
            "amountUSD": 800,
            "priceUSD": 1,
            "liquidityUSD": 180000000,
            "decimals": 6,
            "tokenType": "erc20",
            "security": {
              "isHoneypot": false
            },
            "wallets": {
              "0xwalletA": {
                "amount": 500,
                "amountRaw": "500000000",
                "amountUSD": 500
              },
              "0xwalletB": {
                "amount": 300,
                "amountRaw": "300000000",
                "amountUSD": 300
              }
            }
          },
          "evm:8453": {
            "chainId": "evm:8453",
            "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
            "amount": 450,
            "amountRaw": "450000000",
            "amountUSD": 450,
            "priceUSD": 1,
            "liquidityUSD": 70000000,
            "decimals": 6,
            "tokenType": "erc20",
            "security": null,
            "wallets": {
              "0xwalletA": {
                "amount": 450,
                "amountRaw": "450000000",
                "amountUSD": 450
              }
            }
          }
        }
      }
    ]
  }
}