Migrate from Mobula

A drop-in mapping from the Mobula API to Octav. The biggest wins:

One call instead of two. Mobula splits a portfolio across wallet/portfolio (tokens) and wallet/defi-positions (DeFi). Octav returns wallet tokens, DeFi positions, and net worth from a single GET /v1/portfolio.
Reliable DeFi coverage. Mobula’s DeFi decoding is inconsistent run-to-run. Octav decodes positions consistently across chains and protocols.
Sanity-checked pricing. Mobula can emit long-tail price outliers — a single mispriced defunct token can blow up your total. Octav validates pricing so networth stays trustworthy.
P&L and cost basis come back in the same response.

Get your API key at data.octav.fi. Base URL: https://api.octav.fi/v1.

Endpoint mapping

Use case	Mobula	Octav
Wallet tokens (all chains)	`GET /wallet/portfolio`	`GET /v1/portfolio` → `assetByProtocols.wallet`
DeFi positions	`GET /wallet/defi-positions`	same `GET /v1/portfolio` → `assetByProtocols.<protocol>`
Net worth	`GET /wallet/portfolio` → `total_wallet_balance` (+ DeFi total)	same response → `networth` + `chains`
Transaction history	`GET /wallet/transactions`	`GET /v1/transactions`

Tokens and DeFi both come from a single GET /v1/portfolio call. There is no separate positions request to merge.

Authentication

Mobula uses a raw Authorization header (no scheme prefix). Octav uses a standard Authorization: Bearer token.

curl "https://api.mobula.io/api/1/wallet/portfolio?wallet=0x6426af179aabebe47666f345d69fd9079673f6cd" \
  -H "Authorization: YOUR_MOBULA_KEY"

curl "https://api.octav.fi/v1/portfolio?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd" \
  -H "Authorization: Bearer YOUR_OCTAV_KEY"

Wallet token balances

Mobula’s wallet/portfolio returns data.assets[], a flat array of tokens with per-chain splits in cross_chain_balances. In Octav, wallet tokens live under the wallet protocol, already grouped by chain:

assetByProtocols.wallet.chains.<chain>.protocolPositions.WALLET.assets[]

const OCTAV_KEY = process.env.OCTAV_API_KEY;
const address = "0x6426af179aabebe47666f345d69fd9079673f6cd";

const res = await fetch(
  `https://api.octav.fi/v1/portfolio?addresses=${address}&includeImages=true`,
  { headers: { Authorization: `Bearer ${OCTAV_KEY}` } }
);
const [portfolio] = await res.json(); // /v1/portfolio returns one entry per address

// Flatten wallet tokens across every chain
const wallet = portfolio.assetByProtocols.wallet;
const tokens = Object.values(wallet.chains).flatMap((chain) =>
  Object.values(chain.protocolPositions).flatMap((pos) => pos.assets)
);

tokens.forEach((t) =>
  console.log(`${t.symbol} on ${t.chainKey}: ${t.balance} ($${t.value})`)
);

import os
import requests

OCTAV_KEY = os.environ["OCTAV_API_KEY"]
address = "0x6426af179aabebe47666f345d69fd9079673f6cd"
res = requests.get(
    "https://api.octav.fi/v1/portfolio",
    params={"addresses": address, "includeImages": True},
    headers={"Authorization": f"Bearer {OCTAV_KEY}"},
)
portfolio = res.json()[0]  # one entry per address

wallet = portfolio["assetByProtocols"]["wallet"]
for chain in wallet["chains"].values():
    for pos in chain["protocolPositions"].values():
        for t in pos["assets"]:
            print(f"{t['symbol']} on {t['chainKey']}: {t['balance']} (${t['value']})")

curl "https://api.octav.fi/v1/portfolio?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd&includeImages=true" \
  -H "Authorization: Bearer YOUR_OCTAV_KEY"

Field mapping

Mobula (`data.assets[]`)	Octav (`…assets[]`)	Notes
`asset.symbol`	`symbol`
`asset.name`	`name`
`asset.contracts[]`	`contract`	Per-chain token address. Native tokens use the zero address in Octav.
`cross_chain_balances.<chain>`	per-chain split	Octav splits by `chainKey` natively; no `cross_chain_balances` object to unpack.
`price`	`price`	USD, precomputed.
`token_balance`	`balance`	Human-readable in both.
`estimated_balance`	`value`	USD value of the holding.
`asset.logo`	asset logo (with `includeImages=true`)

Net worth and per-chain breakdown

In Mobula you add data.total_wallet_balance (from wallet/portfolio) to the DeFi positions total to get a full net worth. Octav returns the already-summed networth, plus a per-chain breakdown in chains.

Mobula	Octav	Notes
`data.total_wallet_balance` + DeFi total	`networth`	Single field, tokens and DeFi already summed.
—	`chains.<chain>.value`	Per-chain total (Octav adds this).
—	`chains.<chain>.key` / `chainId`	Chain identifier + numeric ID.
—	`chains.<chain>.valuePercentile`	Share of net worth per chain (Octav adds this).
—	`openPnl` / `closedPnl` / `totalCostBasis`	P&L and cost basis (Octav adds these).

JavaScript

console.log(`Net worth: $${portfolio.networth}`);
Object.values(portfolio.chains).forEach((c) =>
  console.log(`${c.name}: $${c.value} (${c.valuePercentile}%)`)
);

DeFi positions

Mobula returns DeFi from a second call, wallet/defi-positions, as an array of { protocol, positions[] }. Octav returns the same money in the first response under assetByProtocols, keyed by protocol, then chain, then position type (LENDING, LIQUIDITYPOOL, STAKED, FARMING, …).

// Every protocol except the "wallet" bucket is a DeFi position
const defi = Object.entries(portfolio.assetByProtocols).filter(
  ([key]) => key !== "wallet"
);

defi.forEach(([key, protocol]) => {
  console.log(`${protocol.name}: $${protocol.value}`);
  Object.values(protocol.chains).forEach((chain) => {
    Object.entries(chain.protocolPositions).forEach(([type, pos]) => {
      console.log(`  ${type}: $${pos.totalValue}`);
      pos.assets.forEach((a) => console.log(`    ${a.symbol}: $${a.value}`));
    });
  });
});

for key, protocol in portfolio["assetByProtocols"].items():
    if key == "wallet":
        continue
    print(f"{protocol['name']}: ${protocol['value']}")
    for chain in protocol["chains"].values():
        for ptype, pos in chain["protocolPositions"].items():
            print(f"  {ptype}: ${pos['totalValue']}")

Field mapping

Mobula (`defi-positions[]`)	Octav	Notes
`protocol.name`	`assetByProtocols.<key>.name`	Keyed by protocol.
`positions[].type`	position `TYPE` key	e.g. `LENDING`, `LIQUIDITYPOOL`, `STAKED`.
`positions[].chain_id`	`assetByProtocols.<key>.chains.<chain>`	Strip the `evm:` prefix to get the numeric chain id (e.g. `evm:1` → `1`).
`positions[].tokens[].symbol`	asset `symbol`
`positions[].tokens[].amount`	asset `balance`	Human-readable in both.
`positions[].tokens[].amount_usd`	asset `value`	USD value, precomputed.
`protocol.logo`	protocol logo (with `includeImages=true`)

Mobula’s DeFi coverage varies between runs and can miss protocols. Octav decodes positions consistently and folds every protocol into the same assetByProtocols map, so you never call a second endpoint.

Transaction history

Swap Mobula’s wallet/transactions for GET /v1/transactions.

curl "https://api.mobula.io/api/1/wallet/transactions?wallet=0x6426af179aabebe47666f345d69fd9079673f6cd" \
  -H "Authorization: YOUR_MOBULA_KEY"

curl "https://api.octav.fi/v1/transactions?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd" \
  -H "Authorization: Bearer YOUR_OCTAV_KEY"

Octav categorizes each transaction (swap, deposit, stake, bridge, …) and prices transfers in USD. See the transaction types reference.

Key differences

Calls per portfolio. Mobula: wallet/portfolio + wallet/defi-positions. Octav: one GET /v1/portfolio.
DeFi reliability. Mobula’s DeFi decoding is inconsistent run-to-run. Octav decodes positions consistently.
Pricing. Mobula can emit long-tail price outliers that distort totals. Octav sanity-checks pricing so networth stays trustworthy.
Auth header. Mobula sends the raw key in Authorization. Octav uses Authorization: Bearer <key>.
Chains. Both cover EVM and Solana. Octav returns them in the same shape from one endpoint.
Chain ids. Mobula formats DeFi chain ids like evm:1; strip the evm: prefix for the numeric id. Octav keys chains by name (ethereum) with chainId alongside.
Grouping. Mobula returns data.assets[] (tokens) and a separate defi-positions[] array. Octav groups assetByProtocols → chains → protocolPositions → assets[], with a dedicated wallet bucket for loose tokens.
Billing. Mobula charges roughly 1 credit per chain. Octav charges 1 credit per call (see pricing).
P&L. Octav adds openPnl, closedPnl, and totalCostBasis at no extra call.

Getting Started

Endpoints

Playground

AI Development

Migrate to Octav

Reference

Endpoint mapping

Authentication

Wallet token balances

Net worth and per-chain breakdown

DeFi positions

Transaction history

Key differences

Need help migrating?

Join our Discord

Portfolio endpoint

​Endpoint mapping

​Authentication

​Wallet token balances

​Net worth and per-chain breakdown

​DeFi positions

​Transaction history

​Key differences

​Need help migrating?

Join our Discord

Portfolio endpoint

Endpoint mapping

Authentication

Wallet token balances

Net worth and per-chain breakdown

DeFi positions

Transaction history

Key differences

Need help migrating?