> ## 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 GoldRush (Covalent)

> A 1:1 mapping from the GoldRush (Covalent) API to the Octav API

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`](/api/endpoints/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`.

<Info>
  **Get your API key** at [data.octav.fi](https://data.octav.fi/). Base URL: `https://api.octav.fi/v1`. GoldRush already uses `Authorization: Bearer`, so only the base URL and response shape change.
</Info>

## Endpoint mapping

| Use case                   | GoldRush (Covalent)                                                   | Octav                                                                       |
| -------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Wallet tokens (one chain)  | `GET /{chain}/address/{address}/balances_v2/`                         | [`GET /v1/portfolio`](/api/endpoints/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`](/api/endpoints/transactions)                       |

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

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

<CodeGroup>
  ```bash GoldRush theme={null}
  curl "https://api.covalenthq.com/v1/eth-mainnet/address/0x6426af179aabebe47666f345d69fd9079673f6cd/balances_v2/?quote-currency=USD&no-spam=true" \
    -H "Authorization: Bearer YOUR_GOLDRUSH_KEY"
  ```

  ```bash Octav theme={null}
  curl "https://api.octav.fi/v1/portfolio?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd" \
    -H "Authorization: Bearer YOUR_OCTAV_KEY"
  ```
</CodeGroup>

## 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[]
```

<CodeGroup>
  ```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"
  ```
</CodeGroup>

**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](/api/reference/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 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

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

<CodeGroup>
  ```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']}")
  ```
</CodeGroup>

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

## Transaction history

Swap `transactions_v3` for [`GET /v1/transactions`](/api/endpoints/transactions). GoldRush scopes history to one chain per call; Octav returns it for the address across chains.

<CodeGroup>
  ```bash GoldRush theme={null}
  curl "https://api.covalenthq.com/v1/eth-mainnet/address/0x6426af179aabebe47666f345d69fd9079673f6cd/transactions_v3/" \
    -H "Authorization: Bearer YOUR_GOLDRUSH_KEY"
  ```

  ```bash Octav theme={null}
  curl "https://api.octav.fi/v1/transactions?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd" \
    -H "Authorization: Bearer YOUR_OCTAV_KEY"
  ```
</CodeGroup>

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

## 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](/api/pricing)).
* **P\&L.** Octav adds `openPnl`, `closedPnl`, and `totalCostBasis` at no extra call.

## Need help migrating?

<CardGroup cols={2}>
  <Card title="Join our Discord" icon="discord" href="https://discord.com/invite/qvcknAa73A">
    Share your GoldRush response shape and we'll map it.
  </Card>

  <Card title="Portfolio endpoint" icon="chart-pie" href="/api/endpoints/portfolio">
    Full reference for the endpoint you'll be calling.
  </Card>
</CardGroup>