Wallets & Indexers

Self-contained integration guide for wallets and indexers surfacing Arcadia positions across Base, Optimism, and Unichain. Covers Account discovery via the Factory, distinguishing Margin (V3) and Spot

Arcadia Finance is a DeFi yield-earning platform that lets users run leveraged automated-market-maker liquidity strategies on major DEXes (Uniswap, Aerodrome, Velodrome). Under the hood, the Arcadia Protocol provides user-owned, non-custodial smart-contract Accounts that come in two flavours: Margin Accounts (can borrow against deposited collateral) and Spot Accounts (pure asset holders for non-leveraged strategies). Arcadia supports both virtual and concentrated-liquidity positions and is live on Base, Optimism, and Unichain.

This page describes how to surface Arcadia positions in a wallet UI or indexer. End-users do not hold assets directly in their EOA; they hold them in Arcadia Accounts, which are proxy smart contracts owned by the EOA.

All Arcadia contracts are deployed with CREATE2, so the core and periphery addresses are identical on Base, Optimism, and Unichain. The chain-specific differences are:

• Lending pools available (Base: USDC, WETH, cbBTC; Optimism: USDC, WETH; Unichain: USDC, WETH but margin is not yet enabled; no Account versions are currently allowlisted to borrow on Unichain).

• Slipstream V3 Asset Module and wrapper addresses (different on Optimism, which has a separate Velodrome v3 deployment; not deployed on Unichain).

• Underlying DEX deployments (Uniswap V3/V4 position managers, Slipstream / Velodrome position managers).

Chain Deployments

Chain	Chain ID	Block Explorer
Base	8453	basescan.org
Optimism	10	optimistic.etherscan.io
Unichain	130	uniscan.xyz

1. The Factory

The Factory mints a non-transferable-by-itself ERC-721 (ArcadiaAccount) whose tokenId == accountIndex. Each token wraps an Account proxy.

Factory       0xDa14Fdd72345c4d2511357214c5B89A919768e59    (Base + Optimism + Unichain)

The Account NFT IS the right to control the underlying Account proxy. Transferring the NFT transfers the Account.

Key Factory ABI

// ERC-721 over Account ownership.
function ownerOf(uint256 tokenId) external view returns (address);
function balanceOf(address owner) external view returns (uint256);

// Map an Account proxy address to its NFT tokenId (returns 0 if not an Account).
function accountIndex(address account) external view returns (uint256);

// Reverse lookup: get the proxy address for a tokenId (storage array; 0-indexed in code, 1-indexed in NFT id).
function allAccounts(uint256 index) external view returns (address);

// Owner of an Account proxy.
function ownerOfAccount(address account) external view returns (address);

// Is the address an Arcadia Account?
function isAccount(address account) external view returns (bool);

// Total number of Accounts created.
function allAccountsLength() external view returns (uint256);

// Account creation.
function createAccount(uint32 userSalt, uint256 accountVersion, address creditor)
    external returns (address account);

Key Factory events

// ERC-721 mint/transfer, fired on every Account creation and transfer.
event Transfer(address indexed from, address indexed to, uint256 indexed id);

// Account upgraded to a new implementation version.
event AccountUpgraded(address indexed accountAddress, uint88 indexed newVersion);

The simplest way to index "Accounts owned by an EOA" is to subscribe to Transfer on the Factory.

2. Two Account Types: Margin (V3) and Spot (V4)

Each Account is a proxy. Its implementation determines its type. Because of CREATE2, the same implementation addresses are used across chains:

Version	Type	Implementation address
1	Margin (legacy)	0xbea2B6d45ACaF62385877D835970a0788719cAe1
2	Spot (legacy)	0xd8AF1F1dEe6EA38f9c08b5cfa31e01ad2Bfbef28
3	Margin	0x78Db6a136EdD0F70bEd7a6eb5ca2fDF6eE16E8D6
4	Spot	0xe976BFb44f9322164ca6fdA6C5B84fBb6163D442

Per-chain availability:

Version	Base	Optimism	Unichain
1 (Margin, legacy)	available	not used (placeholder)	not used (placeholder)
2 (Spot, legacy)	available	not used (placeholder)	not used (placeholder)
3 (Margin)	available	available	available (no borrow allowlist yet)
4 (Spot)	available	available	available

Legacy caveat. V1 (margin) and V2 (spot) Accounts only exist on Base and are considered legacy. The storage layout and most of the ABI (creditor(), numeraire(), generateAssetData(), getUsedMargin(), balance mappings, Transfers events) are the same as V3/V4, so the same indexing logic works. Newly-created Accounts on Base default to V3/V4; you may still encounter V1/V2 Accounts that were never upgraded.

To determine the type of an Account at runtime, call:

function ACCOUNT_VERSION() external pure returns (uint256);

• ACCOUNT_VERSION() ∈ {1, 3} → Margin Account (can have debt).

• ACCOUNT_VERSION() ∈ {2, 4} → Spot Account (no debt; pure asset holder).

Common state on every Account (from AccountStorageV1)

function owner() external view returns (address);            // current owner (mirrors NFT owner)
function registry() external view returns (address);         // pricing/allowlist registry
function creditor() external view returns (address);         // 0x0 for Spot, LendingPool address for Margin
function numeraire() external view returns (address);        // the unit liabilities are denominated in
function minimumMargin() external view returns (uint96);     // gas-buffer margin (in numeraire decimals)
function liquidator() external view returns (address);       // 0x0 if no creditor

// Internal balance bookkeeping used by Margin (V3) Accounts; written only via routed
// deposit/withdraw flows. Not populated on Spot (V4) Accounts: do NOT use these for V4
// balance queries (see section 4).
function erc20Balances(address token) external view returns (uint256);
function erc1155Balances(address token, uint256 id) external view returns (uint256);

3. Margin Account (V3): Assets and Debt

A Margin Account is linked to exactly one Creditor (a LendingPool). Read it with:

function creditor() external view returns (address);

Possible creditors (LendingPools)

LendingPool addresses are identical on all three chains (CREATE2). The debt-asset address depends on the chain.

Pool	LendingPool address	Underlying (Base)	Underlying (Optimism)	Underlying (Unichain)
USDC	0x3ec4a293Fb906DD2Cd440c20dECB250DeF141dF1	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913	0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85	0x078D782b760474a361dDA0AF3839290b0EF57AD6
WETH	0x803ea69c7e87D1d6C86adeB40CB636cC0E6B98E2	0x4200000000000000000000000000000000000006	0x4200000000000000000000000000000000000006	0x4200000000000000000000000000000000000006
cbBTC	0xa37E9b4369dc20940009030BfbC2088F09645e3B	0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf	not deployed	not deployed

On Unichain, the USDC and WETH LendingPools exist but no Account versions are currently allowlisted to borrow against them. In practice, Unichain Accounts today are all Spot (V4).

(The numeraire of the Account equals the underlying asset of the Creditor.)

The LendingPool itself is an ERC-4626 with the debt token as the underlying. Each pool has a Tranche (an interest-bearing share) and a Wrapped Tranche (ERC-4626 wrapper of the Tranche).

Reading assets in a Margin Account

function generateAssetData()
    external
    view
    returns (
        address[] memory assetAddresses, // ERC-20 / ERC-721 / ERC-1155 contract addresses
        uint256[] memory assetIds,       // 0 for ERC-20; tokenId for ERC-721/1155
        uint256[] memory assetAmounts    // balance for ERC-20/1155; 1 for ERC-721
    );

function getAccountValue(address numeraire_) external view returns (uint256 accountValue);
function getCollateralValue() external view returns (uint256 collateralValue);
function getLiquidationValue() external view returns (uint256 liquidationValue);

generateAssetData() returns three parallel arrays of every asset held in the Account, including ERC-721 LP NFTs and ERC-1155 positions, with no off-chain indexing required.

Reading debt and open liabilities

function getUsedMargin() external view returns (uint256 usedMargin);
function getFreeMargin() external view returns (uint256 freeMargin);
function isAccountUnhealthy() external view returns (bool isUnhealthy);

Note. usedMargin = openDebt + minimumMargin (the latter is a small fixed gas buffer). The bare open liability is:

// On the LendingPool / Creditor:
function getOpenPosition(address account) external view returns (uint256 openPosition);
// openPosition is denominated in the pool's underlying asset (with its native decimals).

Alternative: the user's "debt token" balance is also visible directly through the LendingPool's ERC-4626-like accounting:

function maxWithdraw(address account) external view returns (uint256);  // same value as getOpenPosition

Health metrics (for UI display)

Margin Accounts expose everything needed to render health, borrow capacity, and liquidation risk in the wallet UI. All values are denominated in the Account's numeraire (with that asset's native decimals).

function getAccountValue(address numeraire_) external view returns (uint256 accountValue);   // mark-to-market total
function getCollateralValue() external view returns (uint256 collateralValue);               // MTM minus collateral-factor haircut
function getLiquidationValue() external view returns (uint256 liquidationValue);             // MTM minus liquidation-factor haircut (covers penalty + slippage + auction fees)
function getUsedMargin() external view returns (uint256 usedMargin);                         // openDebt + minimumMargin
function getFreeMargin() external view returns (uint256 freeMargin);                         // max(collateralValue - usedMargin, 0)
function isAccountUnhealthy() external view returns (bool);                                  // collateralValue < usedMargin
function isAccountLiquidatable() external view returns (bool);                               // liquidationValue < usedMargin

Suggested derived metrics for a wallet UI:

• Total value: getAccountValue(numeraire) (raw mark-to-market, ignoring haircuts).

• Net equity: getAccountValue(numeraire) - getOpenPosition(account).

• Borrow capacity remaining: getFreeMargin().

• Health factor (collateral-side): getCollateralValue() / getUsedMargin(). Below 1.0 the Account is unhealthy (cannot borrow more, owner must repay or add collateral).

• Health factor (liquidation-side): getLiquidationValue() / getUsedMargin(). Below 1.0 the Account is liquidatable and may be put up for Dutch auction.

If the Account has no debt (creditor() == 0x0 or getOpenPosition(account) == 0), usedMargin collapses to just minimumMargin and health checks are trivially satisfied.

4. Spot Account (V4): Assets

Spot Accounts have no creditor, no debt, and no generateAssetData(). They are pure asset holders.

Spot Account holdings must be indexed via the token contracts, not the Account itself. V4 does not store any per-asset bookkeeping: _deposit() and _withdraw() only execute the token transfer and emit Transfers. They do not update erc20Balances / erc1155Balances. Those mappings are inherited from AccountStorageV1 but are never written on V4, so they are permanently zero on Spot Accounts (any pre-existing values are cleared by upgradeHook when an Account is upgraded from V1/V2). Combined with the fact that anyone can send tokens directly to the Account proxy with a plain ERC-20 / ERC-721 / ERC-1155 transfer that bypasses the Account entirely, this means neither the Account's Transfers event nor its storage mappings are authoritative.

Index ERC-20 / ERC-721 / ERC-1155 Transfer events on the underlying token contracts, filtered by to == accountProxy (inflows) and from == accountProxy (outflows). For the current balance, call balanceOf(accountProxy) or ownerOf(tokenId) directly on the token contract.

// On the ERC-20 / ERC-721 / ERC-1155 token contract:
event Transfer(address indexed from, address indexed to, uint256 valueOrTokenId);                       // ERC-20 / ERC-721
event TransferSingle(address indexed operator, address indexed from, address indexed to, uint256 id, uint256 value);  // ERC-1155
event TransferBatch (address indexed operator, address indexed from, address indexed to, uint256[] ids, uint256[] values);

function balanceOf(address account) external view returns (uint256);                                    // ERC-20 / ERC-1155 (with id)
function ownerOf(uint256 tokenId) external view returns (address);                                      // ERC-721

5. Arcadia Asset Addresses (LP positions, staked, wrapped)

These are the assets that Margin and Spot Accounts will most commonly hold (on top of plain ERC-20s).

5.1 CL position managers (the assets themselves)

Protocol	Position Manager (Base)	Position Manager (Optimism)	Position Manager (Unichain)
Uniswap V3	0x03a520b32C04BF3bEEf7BEb72E919cf822Ed34f1	0xC36442b4a4522E871399CD717aBDD847Ab11FE88	0x943e6e07a7E8E791dAFC44083e54041D743C46E9
Uniswap V4	0x7C5f5A4bBd8fD63184577525326123B519429bDc	0x3C3Ea4B57a46241e54610e5f022E5c45859A1017	0x4529A01c7A0410167c5740C487A8DE60232617bf
Slipstream V1 (Aero v1 CL / Velo v1 CL)	0x827922686190790b37229fd06084350E74485b72	0x416b433906b1B72FA758e166e239c43d68dC6F29	0x991d5546C4B442B4c5fdc4c8B8b8d131DEB24702
Slipstream V2 (Aero v2 CL)	0xa990C6a764b73BF43cee5Bb40339c3322FB9D55F	(not deployed)	(not deployed)
Slipstream V3 (Aero v3 CL / Velo v3 CL)	0xe1f8cd9AC4e4A65F54f38a5CdAfCA44f6dD68b53	0xf7f8ccce99Ca2896eC75D3A399D152dB96808399	(not deployed)

These are standard Uniswap-V3-style ERC-721 position NFTs. An Arcadia Account can hold them directly (both Spot and Margin).

5.2 Staked Slipstream positions: Asset Modules (also ERC-721)

The Staked Slipstream Asset Modules are themselves the ERC-721 contracts that represent a Slipstream position that has been deposited into its gauge. The position ID is preserved: staked-position id 1000 corresponds to the underlying Slipstream position id 1000 on the relevant position manager.

Asset	Address (Base)	Address (Optimism)	Address (Unichain)
Staked Slipstream V1	0x1Dc7A0f5336F52724B650E39174cfcbbEdD67bF1	0x1Dc7A0f5336F52724B650E39174cfcbbEdD67bF1	0x1Dc7A0f5336F52724B650E39174cfcbbEdD67bF1
Staked Slipstream V2	0xBed6C3E35B9B1e044b3Bc71465769EdFDC0FDD4c	(not deployed)	(not deployed)
Staked Slipstream V3	0xE0F20BE5886F11CbcD2cb5bA9987Bcbbf1d8ca7b	0xF6a87d944204bb5Fdb9CF5534c03c46895f78eCd	(not deployed)
Staked Aerodrome (LP)	0x9f42361B7602Df1A8Ae28Bf63E6cb1883CD44C27	n/a (Aerodrome is Base-only)	n/a
Staked Stargate	0xae909e19fd13C01c28d5Ee439D403920CF7f9Eea	n/a	n/a

ABI for any Staked Slipstream Asset Module (same shape across V1/V2/V3):

// ERC-721
function ownerOf(uint256 tokenId) external view returns (address);
function balanceOf(address owner) external view returns (uint256);

// The reward token (AERO on Base, VELO on Optimism, XVELO on Unichain).
function REWARD_TOKEN() external view returns (address);

// Pending rewards on a position (gauge-style "earned").
function rewardOf(uint256 positionId) external view returns (uint256 rewards);

5.3 Wrapped Staked Slipstream: for Spot Accounts (ERC-721 wrappers)

Margin Accounts can hold Staked Slipstream positions directly. Spot Accounts cannot (they do not price liabilities), so Arcadia exposes Wrapped Staked Slipstream wrappers; these are ERC-721s with the same position id as the underlying Slipstream NFT.

Wrapped Asset	Address (Base)	Address (Optimism)	Address (Unichain)
Wrapped Staked Slipstream V1	0xD74339e0F10fcE96894916B93E5Cc7dE89C98272	0xD74339e0F10fcE96894916B93E5Cc7dE89C98272	0xD74339e0F10fcE96894916B93E5Cc7dE89C98272
Wrapped Staked Slipstream V2	0x147a2CcbAF4521ad209A2875AE0B3c496f4B25a4	(not deployed)	(not deployed)
Wrapped Staked Slipstream V3	0x9189BC25f8faC157B4D87b0b3c14F56bA1477d53	0xC4D3d804ed64C1f78097799208D46b1db4252749	(not deployed)
Wrapped Staked Aerodrome (LP)	0x17B5826382e3a5257b829cF0546A08Bd77409270	n/a	n/a

ABI (same rewardOf semantics as the Staked AM):

function ownerOf(uint256 tokenId) external view returns (address);
function balanceOf(address owner) external view returns (uint256);

function REWARD_TOKEN() external view returns (ERC20);                    // AERO / VELO / XVELO
function POSITION_MANAGER() external view returns (address);              // the underlying Slipstream NPM
function idToGauge(uint256 positionId) external view returns (address);   // the CLGauge backing the wrapped position
function rewardOf(uint256 positionId) external view returns (uint256 rewards);

event RewardPaid(uint256 indexed positionId, address indexed reward, uint128 amount);

Position id transparency. For every "staked" and "wrapped staked" wrapper, the tokenId equals the underlying Slipstream Position Manager tokenId. So position id 1000 on 0x9189BC25f8faC157B4D87b0b3c14F56bA1477d53 (Wrapped Staked Slipstream V1, Base) refers to the same underlying Slipstream V1 liquidity position with id 1000 on 0x827922686190790b37229fd06084350E74485b72. The user's net exposure is: the underlying LP composition + accrued LP fees + accrued gauge rewards (rewardOf(id)).

5.4 Other assets that Arcadia Accounts may hold

Asset	Address (Base)	Notes
Stargate LP (ERC-20)	factory 0xAf5191B0De278C7286d6C7CC6ab6BB8A73bA2Cd6, staking 0x06Eb48763f117c7Be887296CDcdfad2E4092739C	Base only
Aerodrome v1 pools	indexed via Aero factory 0x420DD381b31aEf6683db6B902084cB0FFECe40Da	LP tokens are plain ERC-20s

5.5 Registry and Asset Modules (for advanced lookups)

For programmatic "is this address recognized by Arcadia, and what type is it?":

Registry                       0xd0690557600eb8Be8391D1d97346e2aab5300d5f   (all chains)
ERC20 Primary Asset Module     0xfBecEaFC96ed6fc800753d3eE6782b6F9a60Eed7   (all chains)
Uniswap V3 Asset Module        0x21bd524cC54CA78A7c48254d4676184f781667dC   (all chains)
Uniswap V4 Asset Module        0xb808971ea73341b0d7286B3D67F08De321f80465   (all chains)
Slipstream V1 AM               0xd3A7055bBcDA4F8F49e5c5dE7E83B09a33633F44   (all chains)
Slipstream V2 AM               0x3aDE1F1FdC666B1bFAd376345EA878D1c11EB73B   (Base only)
Slipstream V3 AM (Base)        0xcaf4167dE878Cfb23D9912b1ff5869F2b3527189
Slipstream V3 AM (Optimism)    0xb5bD6B1f9282328B4f21337Fd3BeFe49964627d7
Wrapped Aerodrome AM           0x17B5826382e3a5257b829cF0546A08Bd77409270   (Base only)

6. End-to-end Indexer Pseudocode

// 1) Find all Arcadia Accounts owned by an EOA.
const factory = "0xDa14Fdd72345c4d2511357214c5B89A919768e59";
const balance = await Factory.balanceOf(eoa);
// Either: enumerate via Factory `Transfer` event logs (recommended),
// or page over allAccountsLength() + allAccounts(i) + ownerOfAccount(account) === eoa.

for (const account of accounts) {
  const version = await IAccount(account).ACCOUNT_VERSION();
  const isMargin = version === 1n || version === 3n;
  const creditor = await IAccount(account).creditor();        // 0x0 if Spot

  if (isMargin) {
    // Assets.
    const [addrs, ids, amounts] = await IAccount(account).generateAssetData();
    // Debt.
    const debt = creditor !== ZERO
      ? await ICreditor(creditor).getOpenPosition(account)    // pool's underlying decimals
      : 0n;
    const usedMargin = await IAccount(account).getUsedMargin();   // = debt + minimumMargin
    const collateralValue = await IAccount(account).getCollateralValue();
  } else {
    // Spot: there is no on-chain enumerator AND the Account's own state is not authoritative
    // (direct transfers to the proxy bypass the Account's bookkeeping).
    // Discover holdings by indexing ERC-20/721/1155 `Transfer` events on the token contracts,
    // filtered by `to == account` (inflows) and `from == account` (outflows).
    // For the current balance, query the token contract directly:
    const usdcBal = await IERC20(USDC).balanceOf(account);
  }
}

For Slipstream / Staked Slipstream positions surfaced above:

• Compose the LP token0/token1 underlying via the position manager's positions(id) call.

• Add pending fees from positions(id).tokensOwed0/1 (Uniswap V3 / Slipstream).

• Add pending gauge rewards via rewardOf(id) on the (Wrapped) Staked Slipstream contract.