Migrate from GoldRush (Covalent)

A drop-in mapping from the GoldRush (Covalent) API to Octav. The biggest wins:

Every chain in one call. GoldRush balances are fetched per chain (/{chain}/…/balances_v2) or in batches of at most 10 chains (/allchains/…/balances), so full EVM coverage takes several requests. Octav returns every chain from a single GET /v1/portfolio.
DeFi positions come back. GoldRush is token balances only; its per-protocol DeFi endpoints are deprecated. Octav decodes lending, staking, liquidity, and farming positions in the same response.
Solana in the same shape. Both support Solana tokens. Octav also decodes Solana DeFi and returns it in the identical structure.
Values ready to use. GoldRush returns balance as a raw integer string you divide by 10^contract_decimals. Octav returns a human-readable balance and a precomputed value.

Get your API key at data.octav.fi. Base URL: https://api.octav.fi/v1. GoldRush already uses Authorization: Bearer, so only the base URL and response shape change.

Endpoint mapping

Use case	GoldRush (Covalent)	Octav
Wallet tokens (one chain)	`GET /{chain}/address/{address}/balances_v2/`	`GET /v1/portfolio` → `assetByProtocols.wallet`
Wallet tokens (multichain)	`GET /allchains/address/{address}/balances/?chains=…` (max 10 chains)	same `GET /v1/portfolio` (all chains, one call)
Solana tokens	`GET /solana-mainnet/address/{address}/balances_v2/`	same `GET /v1/portfolio` → `assetByProtocols.wallet`
DeFi positions	deprecated (per-protocol `stacks/*`)	same `GET /v1/portfolio` → `assetByProtocols.<protocol>`
Net worth	none (sum `quote` across calls)	same response → `networth` + `chains`
Transaction history	`GET /{chain}/address/{address}/transactions_v3/`	`GET /v1/transactions`

Tokens, DeFi positions, and net worth all come from a single GET /v1/portfolio call. There is no per-chain loop and no 10-chain batching to merge.

Authentication

Both APIs use a standard Authorization: Bearer token. Only the base URL and the endpoint shape change: GoldRush scopes each request to a chain slug, while Octav takes the address once and returns everything.

curl "https://api.covalenthq.com/v1/eth-mainnet/address/0x6426af179aabebe47666f345d69fd9079673f6cd/balances_v2/?quote-currency=USD&no-spam=true" \
  -H "Authorization: Bearer YOUR_GOLDRUSH_KEY"

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

Wallet token balances

GoldRush’s balances_v2 returns data.items[], a flat array of tokens for one chain. In Octav, wallet tokens live under the wallet protocol, grouped by chain, for every chain at once:

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

GoldRush (`data.items[]`)	Octav (`…assets[]`)	Notes
`contract_address`	`contract`	Token address. Native tokens use the zero address in Octav; GoldRush flags them with `native_token: true`.
`{chain}` slug (request path)	`chainKey`	e.g. `eth-mainnet` → `ethereum`. See supported chains.
`contract_ticker_symbol`	`symbol`
`contract_name`	`name`
`contract_decimals`	`decimal`
`quote_rate`	`price`	USD, precomputed.
`balance` ÷ 10^`contract_decimals`	`balance`	GoldRush returns a raw integer string; Octav returns it human-readable.
`quote`	`value`	Octav returns `value` directly.
`logo_urls.token_logo_url`	asset logo (with `includeImages=true`)
`is_spam`	—	Octav applies its own spam filtering; there is no flag to check.

Net worth and per-chain breakdown

GoldRush has no single net-worth endpoint. You sum quote across every token and every chain call yourself. Octav returns the total directly on the same portfolio response, plus a per-chain breakdown.

GoldRush	Octav	Notes
sum of `quote` across all items and chains	`networth`	Total net worth in USD, precomputed.
sum of `quote` per chain call	`chains.<chain>.value`	Per-chain total.
`{chain}` slug	`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

GoldRush’s per-protocol DeFi endpoints (the stacks/* routes for Aave, Curve, and others) are deprecated and sunset, so there is nothing left to map. This is net-new from Octav: the same portfolio call decodes DeFi positions 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']}")

Solana DeFi is decoded too, in the same assetByProtocols structure. You do not switch endpoints or response shapes between EVM and Solana.

Transaction history

Swap transactions_v3 for GET /v1/transactions. GoldRush scopes history to one chain per call; Octav returns it for the address across chains.

curl "https://api.covalenthq.com/v1/eth-mainnet/address/0x6426af179aabebe47666f345d69fd9079673f6cd/transactions_v3/" \
  -H "Authorization: Bearer YOUR_GOLDRUSH_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. GoldRush: one balances_v2 call per chain, or allchains/balances batched at 10 chains max, plus a separate Solana call. Octav: one GET /v1/portfolio for every chain, EVM and Solana.
DeFi. GoldRush is token balances only; its DeFi position endpoints are deprecated. Octav decodes DeFi positions in the same response.
Values. GoldRush returns balance as a raw integer string you divide by 10^contract_decimals. Octav returns a human-readable balance and a precomputed value.
Net worth. GoldRush has no net-worth endpoint; you sum quote yourself. Octav returns networth and per-chain value directly.
Grouping. GoldRush returns a flat data.items[] per chain. Octav groups assetByProtocols → chains → protocolPositions → assets[], with a dedicated wallet bucket for loose tokens.
Billing. 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?