> ## Documentation Index > Fetch the complete documentation index at: https://docs.octav.fi/llms.txt > Use this file to discover all available pages before exploring further. # Migrate from Zapper > A 1:1 mapping from the Zapper API to the Octav API A drop-in mapping from the **Zapper API** to Octav. The biggest wins: * **A REST GET instead of a GraphQL query.** Zapper makes you write a nested `portfolioV2` query with `edges`, `nodes`, inline fragments, and hand-picked field selections. Octav returns wallet tokens, DeFi positions, and net worth from a single [`GET /v1/portfolio`](/api/endpoints/portfolio) with no query body. * **USD values precomputed.** Both return `balanceUSD` / `value`, but Octav layers on P\&L and cost basis in the same response. * **Deeper, more consistent DeFi decoding.** Zapper is known to under-value Pendle-style yield tokens; Octav decodes them into their underlying assets so positions carry their real value. * **P\&L and cost basis** come back in the same response. **Get your API key** at [data.octav.fi](https://data.octav.fi/). Base URL: `https://api.octav.fi/v1`. ## Endpoint mapping | Use case | Zapper | Octav | | -------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------- | | Wallet tokens (all chains) | `portfolioV2.tokenBalances.byToken` | [`GET /v1/portfolio`](/api/endpoints/portfolio) → `assetByProtocols.wallet` | | DeFi positions | `portfolioV2.appBalances.byApp` | same `GET /v1/portfolio` → `assetByProtocols.` | | Net worth | `tokenBalances.totalBalanceUSD` + `appBalances.totalBalanceUSD` | same response → `networth` + `chains` | | Transaction history | GraphQL activity query | [`GET /v1/transactions`](/api/endpoints/transactions) | | Token metadata / price | field selection on each `node` | inline on every asset (`price`, `value`, `decimal`) | Everything except history comes from a **single** `GET /v1/portfolio` call. There is no GraphQL query to write, and no `tokenBalances` / `appBalances` branches to stitch back together. ## Authentication Zapper uses an `x-zapper-api-key` header on a GraphQL POST. Octav uses a standard `Authorization: Bearer` token on a GET. ```bash Zapper theme={null} curl "https://public.zapper.xyz/graphql" \ -X POST \ -H "Content-Type: application/json" \ -H "x-zapper-api-key: YOUR_ZAPPER_KEY" \ -d '{ "query": "query($addresses: [Address!]!) { portfolioV2(addresses: $addresses) { tokenBalances { totalBalanceUSD byToken(first: 50) { edges { node { symbol tokenAddress balance balanceUSD price network { name } } } } } } }", "variables": { "addresses": ["0x6426af179aabebe47666f345d69fd9079673f6cd"] } }' ``` ```bash Octav theme={null} curl "https://api.octav.fi/v1/portfolio?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd" \ -H "Authorization: Bearer YOUR_OCTAV_KEY" ``` ## Wallet token balances Zapper's `tokenBalances.byToken` returns a paginated connection of `edges { node }`. In Octav, wallet tokens live under the `wallet` protocol, grouped by chain: ``` assetByProtocols.wallet.chains..protocolPositions.WALLET.assets[] ``` ```javascript JavaScript theme={null} 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})`) ); ``` ```python Python theme={null} 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']})") ``` ```bash cURL theme={null} curl "https://api.octav.fi/v1/portfolio?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd&includeImages=true" \ -H "Authorization: Bearer YOUR_OCTAV_KEY" ``` **Field mapping** | Zapper (`tokenBalances.byToken.edges.node`) | Octav (`…assets[]`) | Notes | | ------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `tokenAddress` | `contract` | Token address. Native tokens use the zero address in Octav. | | `network` | `chainKey` | Zapper returns a `network` object; Octav returns a flat chain key. See [supported chains](/api/reference/supported-chains). | | `symbol` | `symbol` | | | `balance` | `balance` | Human-readable in both. | | `price` | `price` | USD, precomputed. | | `balanceUSD` | `value` | Position value in USD. | | — | `name` / `decimal` | Octav returns token name and decimals inline. | ## Net worth and per-chain breakdown Zapper splits net worth across two branches you have to add together. Octav returns the same total on the top-level `networth` field, plus a per-chain `chains` breakdown. | Zapper | Octav | Notes | | --------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------- | | `tokenBalances.totalBalanceUSD` + `appBalances.totalBalanceUSD` | `networth` | Octav sums tokens and DeFi for you. | | per-app `network` totals | `chains..value` | Per-chain total. | | — | `chains..key` / `chainId` | Chain identifier + numeric ID. | | — | `chains..valuePercentile` | Share of net worth per chain (Octav adds this). | | — | `openPnl` / `closedPnl` / `totalCostBasis` | P\&L and cost basis (Octav adds these). | ```javascript JavaScript theme={null} console.log(`Net worth: $${portfolio.networth}`); Object.values(portfolio.chains).forEach((c) => console.log(`${c.name}: $${c.value} (${c.valuePercentile}%)`) ); ``` ## DeFi positions Zapper returns app positions under `appBalances.byApp.edges[].node`, with each position split into `AppTokenPositionBalance` and `ContractPositionBalance` inline fragments, and token roles hidden behind a `metaType` enum. Octav returns the same money under `assetByProtocols`, keyed by protocol, then chain, then position type (`LENDING`, `LIQUIDITYPOOL`, `STAKED`, `FARMING`, …). ```javascript JavaScript theme={null} // 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}`)); }); }); }); ``` ```python Python theme={null} 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** | Zapper (`appBalances.byApp.edges.node`) | Octav | Notes | | ---------------------------------------------- | --------------------------------------- | --------------------------------- | | `app.displayName` | `assetByProtocols..name` | Keyed by protocol. | | `network` | `assetByProtocols..chains.` | | | `balanceUSD` | `protocolPositions..totalValue` | Net position value. | | `positionBalances…tokens.metaType = SUPPLIED` | `assets[]` (supplied) | | | `positionBalances…tokens.metaType = BORROWED` | `assets[]` (borrowed) | Debt is decoded, not netted away. | | `positionBalances…tokens.metaType = CLAIMABLE` | `assets[]` (rewards) | | | inner `token.symbol` / `balanceUSD` | asset `symbol` / `value` | | Zapper is known to under-value Pendle-style yield tokens. Octav decodes those positions into their underlying assets, so `assets[]` and `totalValue` reflect the real position value. ## Transaction history Swap Zapper's GraphQL activity query for [`GET /v1/transactions`](/api/endpoints/transactions). ```bash Zapper theme={null} curl "https://public.zapper.xyz/graphql" \ -X POST \ -H "Content-Type: application/json" \ -H "x-zapper-api-key: YOUR_ZAPPER_KEY" \ -d '{ "query": "query($addresses: [Address!]!) { ... }", "variables": { "addresses": ["0x6426af179aabebe47666f345d69fd9079673f6cd"] } }' ``` ```bash Octav theme={null} 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](/api/reference/transaction-types). ## Key differences * **Protocol shape.** Zapper is a single GraphQL POST with a nested `portfolioV2` query (`edges`, `nodes`, inline fragments, field selection). Octav is one plain `GET /v1/portfolio` with no query body. * **Branches.** Zapper splits a portfolio across `tokenBalances` and `appBalances`, each with its own `totalBalanceUSD`. Octav returns both plus `networth` in one shape. * **Values.** Both return `balanceUSD` / `value`. Octav also returns `openPnl`, `closedPnl`, and `totalCostBasis` at no extra call. * **Grouping.** Zapper groups DeFi by app → `positionBalances` with a `metaType` enum. Octav groups `assetByProtocols` → `chains` → `protocolPositions` → `assets[]`, with a dedicated `wallet` bucket for loose tokens. * **DeFi decoding.** Zapper under-values Pendle-style yield tokens; Octav decodes them into their underlying assets. * **Chains.** Both cover EVM **and** Solana from the same endpoint and shape. * **Billing.** Zapper bills roughly 3 credits per query. Octav charges **1 credit per call** (see [pricing](/api/pricing)). ## Need help migrating? Share your Zapper query shape and we'll map it. Full reference for the endpoint you'll be calling.