Protocol Types

DeFi protocol position types supported by Octav

Octav categorizes DeFi positions into specific protocol types, allowing you to understand how assets are being used across different protocols and strategies.

Protocol Positions - These types appear in the protocolPositions object within the portfolio response

---

Protocol Position Types

All Types

Basic Holdings

WALLET - Direct wallet custody

• Tokens held directly in wallet
• Not deposited into any protocol
• Fully liquid and transferable

LOCKED - Time-locked tokens

• Tokens with transfer restrictions
• Vesting schedules
• Cannot be transferred until unlock date

Lending & Borrowing

LENDING - Supplied assets earning interest

• Aave deposits
• Compound supplies
• Liquidity provided to money markets

DEPOSIT - General protocol deposits

• Funds deposited but not specifically lending
• May earn yield or rewards

NFTLENDING - NFT-backed lending

• NFTs used as collateral
• Borrowing against NFT value

NFTBORROWER - Borrowing with NFT collateral

• Active loan against NFT

NFTLENDER - Lending to NFT borrowers

• Providing liquidity for NFT loans

Liquidity Provision

LIQUIDITYPOOL - DEX liquidity positions

• Uniswap V2/V3 positions
• SushiSwap pools
• Curve pools
• Earn trading fees

NFTLIQUIDITYPOOL - NFT liquidity pools

• Sudoswap positions
• NFT AMMs

Yield Strategies

FARMING - Yield farming positions

• Staking LP tokens for rewards
• Farm protocol tokens
• Multiple reward streams

LEVERAGEDFARMING - Leveraged yield farming

• Borrowed funds used for farming
• Amplified returns (and risks)
• Examples: Alpaca Finance, Gearbox

STAKED - Staking positions

• Protocol staking (e.g., ETH 2.0)
• Single-sided staking
• Earn staking rewards

NFTSTAKED - Staked NFTs

• NFTs staked for rewards
• Gaming NFTs earning yield

YIELD - General yield positions

• Auto-compounding vaults
• Yield aggregators

Vaults

VAULT - Strategy vaults

• Yearn vaults
• Auto-compounding strategies
• Managed yield optimization

VAULT_PS - Vault with protocol-specific features

• Specialized vault mechanics
• Custom strategies

Derivatives

MARGIN - Margin trading positions

• Leveraged spot trades
• Open long/short positions

MARGIN_PS - Protocol-specific margin

• Custom margin implementations

PERPETUALS - Perpetual futures

• Perpetual swaps (dYdX, GMX)
• Funding rate exposure

LEVERAGE - General leveraged positions

• Amplified exposure
• Borrowed capital

OPTIONSBUYER - Long options positions

• Purchased calls or puts
• Defined risk exposure

OPTIONSSELLER - Short options positions

• Sold calls or puts
• Premium collection
• Unlimited risk potential

Trading & Orders

DCA - Dollar-cost averaging positions

• Automated recurring purchases
• Scheduled buy orders
• Time-weighted accumulation

LIMITORDER - Limit order positions

• Pending limit orders
• Price-triggered trades
• Order book positions

Special Categories

AIRDROP - Airdrop allocations

• Claimable airdrop tokens
• Pending distributions
• Protocol rewards

REWARDS - Claimable rewards

• Unclaimed farming rewards
• Staking rewards pending
• Airdrop allocations

VESTING - Vesting schedules

• Team/investor tokens vesting
• Gradual unlock over time

GOVERNANCE - Governance positions

• Locked governance tokens
• Vote-escrowed positions (veTokens)
• Protocol governance power

INVESTMENT - Strategic investments

• Protocol treasury positions
• Long-term holdings

SPOT - Spot trading

• CEX-style spot positions
• On-chain order books

INSURANCEBUYER - Insurance coverage

• Nexus Mutual coverage
• Protocol insurance

INSURANCESELLER - Insurance underwriter

• Capital at risk for premiums
• Providing insurance coverage

NFTFRACTION - Fractionalized NFTs

• Partial NFT ownership
• Fractional.art positions

By Risk Level

1. Low Risk

   Minimal smart contract risk, no liquidation risk:

   • WALLET - Direct custody
   • LOCKED - Time-locked tokens
   • STAKED - Simple staking
   • GOVERNANCE - Governance tokens
2. Medium Risk

   Smart contract risk, potential impermanent loss:

   • LENDING - Money market deposits
   • DEPOSIT - Protocol deposits
   • LIQUIDITYPOOL - DEX liquidity
   • FARMING - Yield farming
   • VAULT - Strategy vaults
   • YIELD - Yield aggregators
   • DCA - Dollar-cost averaging
   • LIMITORDER - Limit orders
   • AIRDROP - Airdrop allocations
3. High Risk

   Liquidation risk, high complexity:

   • LEVERAGE - Leveraged positions
   • MARGIN - Margin trading
   • LEVERAGEDFARMING - Leveraged farming
   • PERPETUALS - Perpetual futures
   • OPTIONSBUYER - Long options
   • OPTIONSSELLER - Short options (highest risk)

Code Examples

TypeScript Enum

export enum ProtocolPositionType {
  AIRDROP = 'AIRDROP',
  DEPOSIT = 'DEPOSIT',
  DCA = 'DCA',
  FARMING = 'FARMING',
  GOVERNANCE = 'GOVERNANCE',
  INSURANCEBUYER = 'INSURANCEBUYER',
  INSURANCESELLER = 'INSURANCESELLER',
  INVESTMENT = 'INVESMENT',
  LENDING = 'LENDING',
  LEVERAGE = 'LEVERAGE',
  LEVERAGEDFARMING = 'LEVERAGED FARMING',
  LIMITORDER = 'LIMITORDER',
  LIQUIDITYPOOL = 'LIQUIDITYPOOL',
  LOCKED = 'LOCKED',
  MARGIN = 'MARGIN',
  MARGIN_PS = 'MARGINPS',
  NFTBORROWER = 'NFTBORROWER',
  NFTFRACTION = 'NFTFRACTION',
  NFTLENDER = 'NFTLENDER',
  NFTLENDING = 'NFTLENDING',
  NFTLIQUIDITYPOOL = 'NFTLIQUIDITYPOOL',
  NFTSTAKED = 'NFTSTAKED',
  OPTIONSBUYER = 'OPTIONSBUYER',
  OPTIONSSELLER = 'OPTIONSSELLER',
  PERPETUALS = 'PERPETUALS',
  REWARDS = 'REWARDS',
  SPOT = 'SPOT',
  STAKED = 'STAKED',
  VAULT = 'VAULT',
  VAULT_PS = 'VAULTPS',
  VESTING = 'VESTING',
  WALLET = 'WALLET',
  YIELD = 'YIELD',
}

All Position Types

[
  "AIRDROP",
  "DEPOSIT",
  "DCA",
  "FARMING",
  "GOVERNANCE",
  "INSURANCEBUYER",
  "INSURANCESELLER",
  "INVESMENT",
  "LENDING",
  "LEVERAGE",
  "LEVERAGED FARMING",
  "LIMITORDER",
  "LIQUIDITYPOOL",
  "LOCKED",
  "MARGIN",
  "MARGINPS",
  "NFTBORROWER",
  "NFTFRACTION",
  "NFTLENDER",
  "NFTLENDING",
  "NFTLIQUIDITYPOOL",
  "NFTSTAKED",
  "OPTIONSBUYER",
  "OPTIONSSELLER",
  "PERPETUALS",
  "REWARDS",
  "SPOT",
  "STAKED",
  "VAULT",
  "VAULTPS",
  "VESTING",
  "WALLET",
  "YIELD"
]

Get Positions by Type

// Filter positions by type
function getPositionsByType(portfolio, type) {
  const positions = [];

  Object.values(portfolio.assetByProtocols).forEach(protocol => {
    Object.values(protocol.chains).forEach(chain => {
      if (chain.protocolPositions[type]) {
        positions.push({
          protocol: protocol.name,
          chain: chain.name,
          position: chain.protocolPositions[type]
        });
      }
    });
  });

  return positions;
}

// Get all lending positions
const lendingPositions = getPositionsByType(portfolio, 'LENDING');
console.log(`Found ${lendingPositions.length} lending positions`);

Calculate Risk Exposure

// Categorize portfolio by risk
const RISK_CATEGORIES = {
  low: ['WALLET', 'LOCKED', 'STAKED', 'GOVERNANCE'],
  medium: ['LENDING', 'DEPOSIT', 'LIQUIDITYPOOL', 'FARMING', 'VAULT', 'YIELD', 'DCA', 'LIMITORDER', 'AIRDROP'],
  high: ['LEVERAGE', 'MARGIN', 'LEVERAGEDFARMING', 'PERPETUALS', 'OPTIONSBUYER', 'OPTIONSSELLER']
};

function calculateRiskExposure(portfolio) {
  const exposure = { low: 0, medium: 0, high: 0 };

  Object.values(portfolio.assetByProtocols).forEach(protocol => {
    Object.values(protocol.chains).forEach(chain => {
      Object.entries(chain.protocolPositions).forEach(([type, position]) => {
        const value = parseFloat(position.totalValue || position.value || 0);

        for (const [risk, types] of Object.entries(RISK_CATEGORIES)) {
          if (types.includes(type)) {
            exposure[risk] += value;
            break;
          }
        }
      });
    });
  });

  return exposure;
}

const risk = calculateRiskExposure(portfolio);
console.log(`Low risk: $${risk.low.toFixed(2)}`);
console.log(`Medium risk: $${risk.medium.toFixed(2)}`);
console.log(`High risk: $${risk.high.toFixed(2)}`);

---

Common Use Cases

Portfolio Analytics

Track asset allocation across DeFi strategies:

function analyzeDefiAllocation(portfolio) {
  const allocation = {};

  Object.values(portfolio.assetByProtocols).forEach(protocol => {
    Object.values(protocol.chains).forEach(chain => {
      Object.entries(chain.protocolPositions).forEach(([type, position]) => {
        const value = parseFloat(position.totalValue || position.value || 0);
        allocation[type] = (allocation[type] || 0) + value;
      });
    });
  });

  // Calculate percentages
  const total = Object.values(allocation).reduce((sum, val) => sum + val, 0);
  const percentages = {};

  Object.entries(allocation).forEach(([type, value]) => {
    percentages[type] = ((value / total) * 100).toFixed(2);
  });

  return { allocation, percentages, total };
}

const analysis = analyzeDefiAllocation(portfolio);
console.log('DeFi Allocation:', analysis.percentages);

Yield Tracking

Monitor all yield-generating positions:

const YIELD_TYPES = [
  'FARMING', 'LEVERAGEDFARMING', 'STAKED',
  'LENDING', 'VAULT', 'YIELD', 'LIQUIDITYPOOL'
];

function getYieldPositions(portfolio) {
  const yieldPositions = [];

  Object.values(portfolio.assetByProtocols).forEach(protocol => {
    Object.values(protocol.chains).forEach(chain => {
      Object.entries(chain.protocolPositions).forEach(([type, position]) => {
        if (YIELD_TYPES.includes(type)) {
          yieldPositions.push({
            protocol: protocol.name,
            chain: chain.name,
            type: type,
            value: position.totalValue || position.value,
            assets: position.assets || []
          });
        }
      });
    });
  });

  return yieldPositions;
}

const yields = getYieldPositions(portfolio);
const totalYield = yields.reduce((sum, p) =>
  sum + parseFloat(p.value), 0
);

console.log(`Total in yield: $${totalYield.toFixed(2)}`);

Liquidation Risk

Identify positions with liquidation risk:

const LIQUIDATION_RISK_TYPES = [
  'LEVERAGE', 'MARGIN', 'MARGIN_PS',
  'LEVERAGEDFARMING', 'PERPETUALS'
];

function checkLiquidationRisk(portfolio) {
  const riskyPositions = [];

  Object.values(portfolio.assetByProtocols).forEach(protocol => {
    Object.values(protocol.chains).forEach(chain => {
      Object.entries(chain.protocolPositions).forEach(([type, position]) => {
        if (LIQUIDATION_RISK_TYPES.includes(type)) {
          riskyPositions.push({
            protocol: protocol.name,
            chain: chain.name,
            type: type,
            value: position.totalValue,
            healthRate: position.healthRate, // If available
            assets: position.assets
          });
        }
      });
    });
  });

  return riskyPositions;
}

const risky = checkLiquidationRisk(portfolio);
if (risky.length > 0) {
  console.warn(`⚠️  ${risky.length} positions with liquidation risk`);
}

---

Best Practices

Check Position Type

Always check the position type before making assumptions:

const position = chain.protocolPositions.LENDING;

if (position) {
  // This is a lending position
  const supplied = position.supplyAssets || [];
  const borrowed = position.borrowAssets || [];

  console.log(`Supplied: ${supplied.length} assets`);
  console.log(`Borrowed: ${borrowed.length} assets`);
}

Handle Missing Types

Not all positions will have all asset types:

const position = chain.protocolPositions.LIQUIDITYPOOL;

// Safely access optional asset arrays
const baseAssets = position?.baseAssets || [];
const quoteAssets = position?.quoteAssets || [];
const rewardAssets = position?.rewardAssets || [];

Calculate Total Value

Use totalValue when available:

function getPositionValue(position) {
  // Prefer totalValue if available
  if (position.totalValue) {
    return parseFloat(position.totalValue);
  }

  // Fall back to summing assets
  const assets = position.assets || [];
  return assets.reduce((sum, asset) =>
    sum + parseFloat(asset.value || 0), 0
  );
}

---

Related Resources

Portfolio Endpoint

See protocol positions in action

Supported Chains

View all supported blockchains

Transaction Types

Understand transaction categorization