API

RockSolid Vault API Documentation

API Version: v1 Last Updated: September 11, 2025 Status: Active

This document describes the RESTful API endpoints for the RockSolid Vaults API.

Base URL

All API endpoints are relative to https://app-integration.rocksolid.network/api/

Allowed Origins

Current CORS whitelist includes:

  • *.rocketpool.net

  • *.rocksolid.network

  • http://localhost:3000 (development)

  • http://localhost:8788 (Wrangler dev)

  • http://localhost:8787 (Wrangler dev alternate)

GET /api/vaults

Returns comprehensive information for all available vaults including metadata, performance data, strategy allocations, and curator information. This endpoint provides the same rich data structure as the individual vault endpoint but optimized for batch operations.

Response:

VaultDataResponse[]

Where VaultDataResponse includes:

// Complete vault metadata structure
{
  vault_id: number;
  name: string;
  symbol: string;
  // ... (see individual vault endpoint for full structure)
}

  • Complete vault metadata (name, symbol, description, addresses, fees, etc.)

  • is_active: boolean field controlling vault visibility

  • Curators array with many-to-many relationship support

  • Rewards array with additional reward information (see Reward object structure in individual vault endpoint)

  • Chain information with blockchain network details

  • Underlying asset information with token metadata and price feeds

  • Latest performance data (per_share_nav, outstanding_shares, estimated_apr)

  • Strategy allocations with percentages and APR data

  • Performance history (limited to 5 records for optimization)

Data Structure: Each vault object in the response array has the same structure as the individual vault endpoint response (see GET /api/vaults/{vault_address} for detailed field descriptions).

To filter only active vaults:

const activeVaults = vaults.filter((vault) => vault.is_active);

Error Responses:

  • 500: Server error

GET /api/vaults/{vault_address}

Returns detailed information for a specific vault identified by its contract address.

Parameters:

  • vault_address (path): Vault contract address (string)

Response:

VaultDataResponse;

See type definition in /src/lib/types/vault.ts. Includes:

  • Complete vault metadata

  • is_active: boolean field controlling vault visibility

  • Curators array with many-to-many relationship support

  • Rewards array with additional reward token information

  • Chain information with blockchain network details

  • Underlying asset information with token metadata and price feeds

  • Latest performance data

  • Strategy allocations with percentages

  • Performance history (last 30 records)

Error Responses:

  • 404: Vault not found

  • 500: Server error

Example Response Structure:

{
  "vault_id": 1,
  "name": "Balanced rETH Vault",
  "symbol": "brETH",
  "description": "A diversified vault for rETH holders",
  "is_active": true,
  "vault_address": "0x56bf650cfb09396dc1ee845b0049d839b2b7d854",
  "chainId": 8453,
  "priority": 100,
  "curators": [
    {
      "curator_id": 1,
      "name": "Tulipa",
      "logo_url": "https://example.com/tulipa-logo.png"
    }
  ],
  "rewards": [
    {
      "reward_id": 1,
      "name": "Morpho",
      "logo": "https://example.com/morpho-logo.png",
      "classification": "Token",
      "is_active": true
    },
    {
      "reward_id": 2,
      "name": "Beefy",
      "logo": "https://example.com/beefy-logo.png",
      "classification": "Points",
      "is_active": true
    }
  ],
  "platform": {
    "platform_id": 1,
    "name": "Base",
    "logo_url": "https://example.com/base-logo.png"
  },
  "chain": {
    "chain_database_id": 1,
    "chain_id": 8453,
    "name": "Base",
    "logo_url": "https://basescan.org/assets/base/images/svg/logos/chain-light.svg",
    "explorer_url": "https://basescan.org"
  },
  "underlying_asset": {
    "token_id": 2,
    "symbol": "rETH",
    "name": "Rocket Pool ETH",
    "icon": "/logos/r-eth.svg",
    "address": "0xae78736cd615f374d3085123a210448e74fc6393",
    "decimals": 18,
    "price_feed_id": "0x52f9f30dceaba7cca1e54cec3bb4024e8c471307",
    "price_feed_token": "ETH",
    "is_active": true,
    "chain_database_id": 1
  },
  "performance_history": [...],
  "allocations": [...]
}

Reward Object Structure:

The rewards array contains Reward objects with the following structure:

interface Reward {
  reward_id: number;          // Unique reward identifier
  name: string;              // Reward name (e.g., "Arbitrum", "Optimism")
  logo: string;              // URL to reward token logo image
  classification: string;     // Type of reward ("Token", "Points", "NFT")
  is_active: boolean;        // Whether reward is currently active
}

Note: Only active rewards (is_active: true) are returned in API responses.

Caching: 5 minutes (300 seconds)

GET /api/vaults/{vault_address}/allocations

Returns allocation snapshots for a specific vault and allocation period, including optional performance notes.

Parameters:

  • vault_address (path): Vault contract address (string)

  • period-id (query): Allocation period ID (integer, required)

Response:

GetAllocationSnapshotsResponse;

See type definition in /src/lib/types/vault.ts. The response structure includes:

{
  snapshots: AllocationSnapshot[];
  performance_note?: PerformanceNote;
}

AllocationSnapshot Structure: Each allocation snapshot includes:

  • id: string (allocation ID)

  • strategy: string (strategy name)

  • description: string (strategy position)

  • logoUrl: string | undefined (strategy logo)

  • allocation: number (percentage as decimal, e.g., 0.20 = 20%)

  • strategyApr: number (APR as decimal, e.g., 0.05 = 5%)

  • ongoingApr: number | null (ongoing APR as decimal)

  • pendingApr: number | null (pending APR as decimal)

  • totalApr: number (total APR as decimal)

PerformanceNote Structure (optional): If a performance note exists for the vault and allocation period:

  • vault_performance_note_id: number (note ID)

  • title: string (note title)

  • content: string (note content/description)

  • url: string | undefined (optional URL reference)

Data Transformations:

  • Allocation percentages are converted from basis points to decimals (stored value ÷ 100)

  • APR values are converted from basis points to decimals (stored value ÷ 100)

  • Returns empty snapshots array if vault has no allocations

  • Performance note is undefined if no note exists for this vault/period combination

Example Response (with performance note):

{
  "snapshots": [
    {
      "id": "25",
      "strategy": "Aave USDC Lending",
      "description": "Long",
      "logoUrl": "https://example.com/aave-logo.png",
      "allocation": 0.455,
      "strategyApr": 0.0525,
      "ongoingApr": 0.0525,
      "pendingApr": null,
      "totalApr": 0.0525
    },
    {
      "id": "26",
      "strategy": "Compound ETH Lending",
      "description": "Long",
      "logoUrl": "https://example.com/compound-logo.png",
      "allocation": 0.545,
      "strategyApr": 0.048,
      "ongoingApr": 0.048,
      "pendingApr": 0.012,
      "totalApr": 0.06
    }
  ],
  "performance_note": {
    "vault_performance_note_id": 1,
    "title": "Q3 2025 Performance Update",
    "content": "Strong performance driven by increased lending rates on Aave and successful strategy rebalancing. ETH positions benefited from market volatility.",
    "url": "https://docs.rocksolid.network/performance/q3-2025"
  }
}

Example Response (without performance note):

{
  "snapshots": [
    {
      "id": "27",
      "strategy": "Uniswap ETH/USDC LP",
      "description": "Long",
      "allocation": 1.0,
      "strategyApr": 0.035,
      "ongoingApr": 0.035,
      "pendingApr": null,
      "totalApr": 0.035
    }
  ]
}

Error Responses:

  • 400: Missing or invalid period-id parameter

  • 404: Vault or allocation period not found

  • 500: Server error

Caching: 5 minutes (300 seconds) with custom Cache-Control headers (s-maxage=300, stale-while-revalidate=300)

GET /api/vaults/allocation-periods

Returns all available allocation periods for use in date selectors and period navigation.

Response:

GetAllocationPeriodsResponse;

Structure:

{
  periods: AllocationPeriodItem[];
  total: number;
}

Where AllocationPeriodItem includes:

  • allocation_period_id: number

  • period_start: Date (Unix timestamp)

  • period_end: Date (Unix timestamp)

Data Ordering: Results are ordered by period_start in descending order (newest first).

Error Responses:

  • 500: Server error

Caching: No explicit caching configured (relies on default Next.js behavior)

GET /api/vaults/{vault_address}/apr

Returns calculated Annual Percentage Rate (APR) and Total Value Locked (TVL) for a specific vault, with enhanced APR calculations for rETH vaults.

Parameters:

  • vault_address (path): Vault contract address (string, automatically normalized to lowercase)

  • days_to_compute (query, optional): Number of days to use for APR calculation (integer, default: 14, must be positive)

Response:

{
  tvlRaw: string; // Total value locked in wei (string to prevent precision loss and serialization issues)
  apr: string; // APR as percentage string against underlying asset (e.g., "12.34")
  baseAprAgainstEth: string; // Base APR against ETH for rETH vaults (e.g., "3.45")
  strategyAprAgainstEth: string; // Strategy APR against ETH for rETH vaults (e.g., "8.89")
  totalAprAgainstEth: string; // Total APR against ETH for rETH vaults (e.g., "12.34")
}

Usage: This endpoint combines subgraph event data with Lagoon Protocol SDK calculations to provide accurate performance metrics. APR calculation adapts based on vault maturity (inception APR for vaults <30 days, historical calculation for mature vaults).

Enhanced rETH APR Calculations: For rETH vaults, the endpoint provides additional APR breakdowns against ETH to show the relative performance compared to holding ETH directly.

Implementation Details:

  • Vault address is automatically normalized to lowercase

  • Chain ID is automatically determined from the vault's database record (no longer needs to be provided)

  • Uses GraphQL subgraph queries to fetch vault events

  • Integrates rETH-specific APR calculations via getRethAprCalculation

  • Error responses include detailed error messages for debugging

Error Responses:

  • 400: Invalid days_to_compute parameter (not a positive integer)

  • 404: Vault not found

  • 500: Subgraph query failed, no events found for vault address, or server error

Caching: 5 minutes (300 seconds)

Error Response Format

Most endpoints return errors in this format:

{
  error: string; // Brief error description
  message: string; // Detailed error message
}

PreviousSmart ContractsNextPrice Data Feed

Last updated