> ## 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.

# Build a simple app with multi-chain prices, wallet balances, and transaction history

> Use Mobula to fetch real-time market data, wallet holdings, and a clean activity feed across multiple chains without running your own nodes.

Mobula allows you to build a Web3 app that has **real-time prices**, **wallet holdings**, and a clean **activity feed** across multiple chains, without running your own RPC nodes or stitching together multiple providers.

**Quick Start:** Get your API key at [here](https://admin.mobula.io/), then call the endpoints below from your backend or serverless functions.

***

## Overview

* **Market data** for a token or pool (price, liquidity, volume, price changes)
* **Wallet holdings** (balances + USD values + allocation)
* **Wallet activity** (transfers + swaps + vault operations), ideally normalized into a UI-friendly feed

You can cover these with:

* GET `/api/2/market/details` [Market Details](https://docs.mobula.io/rest-api-reference/endpoint/market-details)
* GET `/api/1/wallet/portfolio` [Crypto Holdings](https://docs.mobula.io/rest-api-reference/endpoint/wallet-portfolio)
* GET `/api/2/wallet/activity` [Wallet Activity](https://docs.mobula.io/rest-api-reference/endpoint/wallet-activity)

***

## 1) Get real-time price, liquidity, volume, and price changes

### Endpoint

[Market Details](https://docs.mobula.io/rest-api-reference/endpoint/market-details)

### When to use

* Token price panels
* Pair pages (liquidity, volume, trades, latest trade)
* Multi-timeframe change and volume stats (1m, 5m, 1h, 24h, etc.)
* Multi-currency display (USD + EUR/GBP/JPY, etc.)

### Required params

* `blockchain` (example: `evm:1`, `solana`, `ethereum`)
* `address` (token address or direct pool address)

### Optional

* `currencies=EUR,USD` (adds converted fields like `priceEUR`, `volume24hEUR`, etc.)

#### Single query example

```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/market/details?blockchain=solana&address=YOUR_TOKEN_OR_POOL" \
  -H "Authorization: YOUR_API_KEY"
```

#### Multiple currency example

```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/market/details?blockchain=solana&address=YOUR_TOKEN_OR_POOL&currencies=EUR,USD" \
  -H "Authorization: YOUR_API_KEY"
```

### What you typically read from the response

* `priceUSD` (and `price{CURRENCY}` if requested)

* `liquidityUSD`

* `volume{timeframe}USD` (ex: `volume24hUSD`)

* `priceChange{timeframe}Percentage` (ex: `priceChange24hPercentage`)

* `latestTradeDate`

* token metadata in `base` and `quote` (symbol, name, decimals, market cap fields, etc.)

* `exchange` (DEX name + logo) when relevant

### Batch markets (for dashboards / watchlists)

This endpoint supports **POST batch** so you can request multiple markets in one call.

```bash theme={null}
curl -X POST "https://api.mobula.io/api/2/market/details" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '[
    {"blockchain":"evm:1","address":"0x..."},
    {"blockchain":"solana:solana","address":"So..."}
  ]'
```

Use this for:

* watchlists
* "top tokens" panels
* loading many token cards efficiently

## 2) Get wallet balances and holdings across chains

### Endpoint

[Crypto Holdings](https://docs.mobula.io/rest-api-reference/endpoint/wallet-portfolio)

### When to use

* Portfolio page: token list, balances, USD values, allocation

* Multi-wallet aggregation (users with multiple addresses)

* Cross-chain wallets (EVM + Solana)

### Input rules

* `wallet=addr...` (single wallet)

* `wallets=addr1,addr2,...` (multiple wallet view, accept comma-separated addresses)

### Performance tip

For fastest responses, specify only the chains you need:

* `blockchains=ethereum,base`
  If you truly need everything: `fetchAllChains=true`

#### Single wallet, specific chains

```bash theme={null}
curl -X GET "https://api.mobula.io/api/1/wallet/portfolio?wallet=0xYOUR_WALLET&blockchains=ethereum,base" \
  -H "Authorization: YOUR_API_KEY"
```

#### Cached responses (good for UI refresh loops)

```bash theme={null}
curl -X GET "https://api.mobula.io/api/1/wallet/portfolio?wallet=0xYOUR_WALLET&blockchains=ethereum,base&cache=true&stale=300" \
  -H "Authorization: YOUR_API_KEY"
```

#### Multiple wallets aggregated

```bash theme={null}
curl -X GET "https://api.mobula.io/api/1/wallet/portfolio?wallets=0xA,0xB&blockchains=ethereum" \
  -H "Authorization: YOUR_API_KEY"
```

### What you typically read from the response

Top-level:

* `total_wallet_balance` (USD)

* `assets[]` (your holdings table)

Per asset in `assets[]`:

* `token_balance`

* `price` (USD)

* `estimated_balance` (USD)

* `allocation`

* `liquidity`

* optional `price_change_24h` if you use `shouldFetchPriceChange=24h`

Also note: native gas tokens are normalized as:

* `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`

So you can reliably detect “native ETH / native SOL equivalent” style balances without guessing.

## 3) Get a clean, UI-ready transaction history feed

### Endpoint

[Wallet Activity](https://docs.mobula.io/rest-api-reference/endpoint/wallet-activity)

### When to use

* “Recent activity” feed

* Basic transaction history for a wallet

* Swap detection (so you can show swaps cleanly)

### Why it's handy

This endpoint **combines transfers into swaps** when they happen in the same transaction. That means your UI gets a single “swap” action instead of scattered token in/out transfers.

### Minimal example

```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/wallet/activity?wallet=0xYOUR_WALLET&limit=40&order=desc" \
  -H "Authorization: YOUR_API_KEY"
```

### Multi-chain + spam filtering

```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/wallet/activity?wallet=0xYOUR_WALLET&blockchains=ethereum,base&filterSpam=true&unlistedAssets=true&limit=40" \
  -H "Authorization: YOUR_API_KEY"
```

### Pagination options

* Offset pagination: `offset` + `limit`
* Cursor pagination: `cursorHash` + `cursorDirection=before|after`
  Useful for infinite scroll feeds.

### Reading swaps correctly (important)

Naming is wallet-centric:

* `swapAssetIn` = asset received by the wallet
* `swapAssetOut` = asset spent by the wallet

To infer buy/sell for the base token:

* BUY if `swapAssetIn` matches `swapBaseAddress`
* SELL if `swapAssetOut` matches `swapBaseAddress`

***

## Putting it together (recommended flow)

If you’re building a typical app UI:

1. Portfolio page

* Call `/wallet/portfolio` to get holdings, USD values, allocations

2. Market panels for tokens

* For tokens the user holds (or for watchlists), call `/market/details` (batch via POST if you have many)

3. Activity feed

* Call `/wallet/activity` for a clean list of swaps + transfers
* Use cursor pagination for infinite scroll

This gives you a full “wallet dashboard” experience without running nodes.

***

## Production tips

* **Specify chains** whenever possible (`blockchains=ethereum,base`) to cut latency.

* Use **cache + stale** for portfolio screens that refresh frequently.

* Keep spam filtering enabled by default (`filterSpam=true`) and add a UI toggle if power users want raw data.

* If you need richer swap metadata, enable `enrichSwaps=true` (adds some overhead, but can be useful for showing platform + fee breakdown).