Migrate from Zerion

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

A flat, already-priced object. Zerion returns JSON:API (data[].attributes, related entities via relationships) that you traverse and stitch together. Octav returns a flat object where every asset is already USD-priced from a single GET /v1/portfolio.
Compact responses. Zerion payloads can grow very large. Octav responses stay compact.
Decode once, no double-counting. On LST and vault wallets Zerion can surface a receipt token as a wallet position and again as its decoded deposit/staked position, so a naive sum counts it twice. Octav decodes each asset once.
Deeper protocol decoding. Perps, options, and complex positions come back fully decoded, and P&L and cost basis ship in the same response.

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

Endpoint mapping

Use case	Zerion	Octav
Wallet tokens (all chains)	`GET /wallets/{address}/positions?filter[positions]=only_simple`	`GET /v1/portfolio` → `assetByProtocols.wallet`
DeFi positions	`GET /wallets/{address}/positions?filter[positions]=only_complex`	same `GET /v1/portfolio` → `assetByProtocols.<protocol>`
Net worth	`GET /wallets/{address}/portfolio`	same response → `networth` + `chains`
Transaction history	`GET /wallets/{address}/transactions`	`GET /v1/transactions`
Token metadata / price	`fungible_info` on each position	inline on every asset (`price`, `value`, `decimal`)

Everything except history comes from a single GET /v1/portfolio call. There is no only_simple / only_complex filter to run twice and merge.

Authentication

Zerion uses HTTP Basic auth: your API key followed by a colon, base64-encoded, in an Authorization: Basic header. Octav uses a standard Authorization: Bearer token.

# Basic auth: base64("YOUR_ZERION_KEY:") — note the trailing colon
curl "https://api.zerion.io/v1/wallets/0x6426af179aabebe47666f345d69fd9079673f6cd/positions?filter[positions]=only_simple&sort=-value" \
  -H "Authorization: Basic $(printf 'YOUR_ZERION_KEY:' | base64)"

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

Wallet token balances

Zerion’s only_simple positions return a JSON:API array where each token lives under data[].attributes. 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

Zerion (`only_simple` position)	Octav (`…assets[]`)	Notes
`attributes.fungible_info.symbol`	`symbol`
`attributes.fungible_info.name`	`name`
`attributes.quantity.float`	`balance`	Human-readable in both.
`attributes.price`	`price`	USD, precomputed.
`attributes.value`	`value`	Octav’s `value` is always populated; Zerion’s can be `null`.
`attributes.fungible_info.implementations[].address`	`contract`	Token address. Native tokens use the zero address in Octav.
`attributes.fungible_info.implementations[].decimals`	`decimal`
`relationships.chain.data.id`	`chainKey`	e.g. `ethereum`. See supported chains.
`attributes.flags.displayable`	—	Octav applies its own spam filtering; there is no `displayable` flag to check.

Net worth and per-chain breakdown

Zerion’s /portfolio endpoint maps directly onto the top-level networth and chains fields returned by the same portfolio call.

Zerion (`/portfolio`)	Octav	Notes
`data.attributes.total.positions`	`networth`	Total net worth in USD.
`data.attributes.positions_distribution_by_chain.<chain>`	`chains.<chain>.value`	Per-chain total.
—	`chains.<chain>.key` / `chainId`	Chain identifier + numeric ID (Octav adds this).
—	`chains.<chain>.valuePercentile`	Share of net worth per chain (Octav adds this).
`data.attributes.changes.absolute_1d` (24h change)	—	No direct equivalent; Octav returns `openPnl` / `closedPnl` / `totalCostBasis` instead.

JavaScript

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

DeFi positions

Zerion returns decoded positions under only_complex, each with a position_type (deposit, loan, staked, reward, locked). 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

Zerion (`only_complex` position)	Octav	Notes
`attributes.protocol`	`assetByProtocols.<key>.name`	Keyed by protocol.
`attributes.position_type` = `deposit`	`assets[]` (supplied)
`attributes.position_type` = `loan`	`assets[]` (borrowed)	Debt is decoded, not netted away.
`attributes.position_type` = `staked`	`assets[]` (staked)
`attributes.position_type` = `reward`	`assets[]` (rewards)
`attributes.value`	`protocolPositions.<TYPE>.totalValue`	Contributes to the net position value.
`relationships.chain.data.id`	`assetByProtocols.<key>.chains.<chain>`

On LST and vault wallets, Zerion can list a receipt token twice — once as a wallet position and again as its decoded deposit/staked position. Octav decodes each asset once, so summing assetByProtocols never double-counts.

Transaction history

Swap GET /wallets/{address}/transactions for GET /v1/transactions.

curl "https://api.zerion.io/v1/wallets/0x6426af179aabebe47666f345d69fd9079673f6cd/transactions" \
  -H "Authorization: Basic $(printf 'YOUR_ZERION_KEY:' | base64)"

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

Response shape. Zerion returns JSON:API — you walk data[].attributes and resolve related entities through relationships. Octav returns a flat object; no JSON:API traversal.
Payload size. Zerion responses can be very large. Octav responses stay compact.
Values. Zerion’s attributes.value can be null; Octav returns a populated value (and price) on every asset.
Decode once. Zerion may surface an LST/vault receipt token as both a wallet and a deposit/staked position. Octav decodes each asset once, so naive sums don’t double-count.
Grouping. Zerion splits only_simple vs only_complex and groups by position_type. Octav groups assetByProtocols → chains → protocolPositions → assets[], with a dedicated wallet bucket for loose tokens.
Chains. Both cover EVM and Solana. Octav serves both from one flat response and shape.
Billing. Octav charges 1 credit per call (see pricing).
P&L. Octav adds openPnl, closedPnl, and totalCostBasis at no extra call.
NFTs. Octav’s /portfolio focuses on fungible assets and DeFi positions; it does not enumerate NFTs the way Zerion’s /nft-positions does.

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?