Migrate from Zapper

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 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. Base URL: https://api.octav.fi/v1.

Endpoint mapping

Use case	Zapper	Octav
Wallet tokens (all chains)	`portfolioV2.tokenBalances.byToken`	`GET /v1/portfolio` → `assetByProtocols.wallet`
DeFi positions	`portfolioV2.appBalances.byApp`	same `GET /v1/portfolio` → `assetByProtocols.<protocol>`
Net worth	`tokenBalances.totalBalanceUSD` + `appBalances.totalBalanceUSD`	same response → `networth` + `chains`
Transaction history	GraphQL activity query	`GET /v1/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.

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"] }
  }'

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

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.
`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.<chain>.value`	Per-chain total.
—	`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

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, …).

// 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

Zapper (`appBalances.byApp.edges.node`)	Octav	Notes
`app.displayName`	`assetByProtocols.<key>.name`	Keyed by protocol.
`network`	`assetByProtocols.<key>.chains.<chain>`
`balanceUSD`	`protocolPositions.<TYPE>.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.

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"] } }'

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

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

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?