Developer access

Valueverse API

Serve-backed product API for token economics, screener rows, history series, and curated charts. The public contract lives on the Vega read plane, not in Next.js route handlers.

Methodology

Base URL

api-vega.valueverse.ai

Preview and local clients may override this with VALUEVERSE_GATEWAY_BASE_URL.

Auth

Bearer

Use an app-issued vv_* API key. Internal BFF routes stay private.

Contract

{ data, meta }

Errors use RFC 9457 application/problem+json.

Quickstart

Start with a token snapshot or the screener. The product OpenAPI file is served by the gateway at /openapi-product.json.

curl https://api-vega.valueverse.ai/v1/tokens/aave \
  -H "Authorization: Bearer vv_test_<your-key>" \
  -H "Accept: application/json"

OpenAPI

/openapi-product.json

Product-only spec generated by the Rust serve binary. App codegen still uses the broader gateway spec.

Private BFF

/v1/internal/*

Used by the web app with X-Api-Key. Do not build external clients on it.

Decimals

JSON strings

Money and ratio values preserve decimal precision across clients.

Endpoints

Public product routes expose the same read plane the app uses, with consumer envelopes and source metadata.

GET/v1/tokensBearer

Active Valueverse token catalog. Use this before drilling into token snapshots or charts.

GET/v1/screenerBearer

Computed multiplier table: effective market cap, holder revenue, P/FCF windows, streams, freshness, and context market data.

GET/v1/tokens/{slug}Bearer

Token product snapshot: meta, KPI cards, revenue functions, fundamentals, methodology cards, value drivers, section states, verification summary, and chart definitions.

GET/v1/tokens/{slug}/metrics/historyBearer

Normalized history series from the serve trend read model. Query with period=7d|30d|90d|180d|365d|1y.

GET/v1/tokens/{slug}/chartsBearer

Curated chart catalog for a token, including chart key, title, supported timeframes, and data endpoint href.

GET/v1/tokens/{slug}/charts/{chart_key}Bearer

Renderer-neutral chart rows plus combo-chart config. Query with timeframe=7d|30d|90d|180d|365d|1y|all.

Responses

Every successful product route returns a data/meta envelope. Meta carries served time, source surface, optional asOf, and optional count.

Envelope

{ data, meta }

Lists and single resources share the same wrapper.

Source

meta.source

Identifies serve surface, backing read model, chart key, and timeframe when relevant.

// GET /v1/tokens/aave  ->  200
{
  "data": {
    "meta": {
      "tokenId": 1,
      "symbol": "AAVE",
      "name": "Aave",
      "slug": "aave",
      "chain": "Ethereum Mainnet",
      "protocolType": "lending",
      "priceUsd": "264.31",
      "imageUrl": "https://..."
    },
    "combinedRevenue": {
      "annualized": "129000000",
      "allTime": null,
      "deltaPct": null,
      "deltaAbs": null
    },
    "sections": {
      "trend": { "supported": true, "state": "ready", "reason": null, "asOf": null },
      "charts": { "supported": true, "state": "ready", "reason": null, "asOf": null }
    },
    "chartDefs": []
  },
  "meta": {
    "servedAt": "2026-06-30T09:01:12Z",
    "asOf": "2026-06-29",
    "count": null,
    "source": {
      "type": "vega_serve",
      "surface": "token_snapshot",
      "backing": "analytics_read",
      "chartKey": null,
      "timeframe": null
    }
  }
}

Token catalog

GET /v1/tokens

{ data: ProductTokenCatalogItem[], meta }

slugsymbolnamehrefmeta.countmeta.source

Small selector surface. It intentionally does not pretend to be a market-data token list.

Screener

GET /v1/screener

{ data: ScreenerRowOut[], insights: [], meta }

priceUsdeffMcaprevAnnualizedmultAnnualizedwindowsstreamsdataFreshness

The same read model that feeds the product table. Decimal money/ratio values are serialized as strings.

Token snapshot

GET /v1/tokens/{slug}

{ data: TokenPageShell, meta }

metakpisrevenueFunctionscombinedRevenuefundamentalsmethodologysectionsverification

This is the product shell contract. Clients should use sections and verification for agent alerts, not as visible end-user badges.

Metric history

GET /v1/tokens/{slug}/metrics/history

{ data: TrendData | null, meta }

timesseries[].keyseries[].valuesmeta.asOfmeta.source.timeframe

Current serve-backed normalized history. A null data field means the series is not materialized for that token/period.

Chart data

GET /v1/tokens/{slug}/charts/{chart_key}

{ data: ChartItemOut, meta }

idtypedatacurrentTimeframedataFromdataThroughconfig

Chart row schemas are token-specific. Inspect config.series and row keys instead of hardcoding columns.

Examples

Use these calls from agents, scripts, notebooks, or server code. Browser clients should respect rate-limit headers.

Chart fetch

curl "https://api-vega.valueverse.ai/v1/tokens/aave/charts/revenue?timeframe=90d" \
  -H "Authorization: Bearer vv_test_<your-key>" \
  -H "Accept: application/json"

TypeScript

const baseUrl = process.env.VALUEVERSE_GATEWAY_BASE_URL ?? "https://api-vega.valueverse.ai";

const res = await fetch(new URL("/v1/screener", baseUrl), {
  headers: {
    accept: "application/json",
    authorization: `Bearer ${process.env.VALUEVERSE_API_KEY}`,
  },
});

if (!res.ok) throw new Error(`Valueverse API failed: ${res.status}`);
const payload = await res.json();

Python

import os
import requests

base_url = os.getenv("VALUEVERSE_GATEWAY_BASE_URL", "https://api-vega.valueverse.ai")
res = requests.get(
    f"{base_url}/v1/tokens/aave/metrics/history",
    params={"period": "90d"},
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {os.environ['VALUEVERSE_API_KEY']}",
    },
    timeout=20,
)
res.raise_for_status()
payload = res.json()

Headers

Handlers and middleware expose cache, source, rate-limit, retry, and request correlation headers.

Cache-ControlX-Valueverse-SourceX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-ResetRetry-AfterX-Request-Id

Errors

Failures use the gateway problem-details contract. Public handlers remap instance paths to /v1/*, never /v1/internal/*.

400invalid-parameter

Invalid slug, chart key, period, or timeframe.

404token-not-found / chart-item-not-found

The requested token or chart is not covered.

429rate-limit-exceeded

The public IP bucket exceeded the configured request budget.

503service-unavailable

The serve read plane, database, or materialized view is unavailable.

500internal-error

Unexpected server failure. Response includes request id headers for tracing.

// GET /v1/tokens/aave -> 200 { "data": { "meta": { "tokenId": 1, "symbol": "AAVE", "name": "Aave", "slug": "aave", "chain": "Ethereum Mainnet", "protocolType": "lending", "priceUsd": "264.31", "imageUrl": "https://..." }, "combinedRevenue": { "annualized": "129000000", "allTime": null, "deltaPct": null, "deltaAbs": null }, "sections": { "trend": { "supported": true, "state": "ready", "reason": null, "asOf": null }, "charts": { "supported": true, "state": "ready", "reason": null, "asOf": null } }, "chartDefs": [] }, "meta": { "servedAt": "2026-06-30T09:01:12Z", "asOf": "2026-06-29", "count": null, "source": { "type": "vega_serve", "surface": "token_snapshot", "backing": "analytics_read", "chartKey": null, "timeframe": null } } }

import os import requests base_url = os.getenv("VALUEVERSE_GATEWAY_BASE_URL", "https://api-vega.valueverse.ai") res = requests.get( f"{base_url}/v1/tokens/aave/metrics/history", params={"period": "90d"}, headers={ "Accept": "application/json", "Authorization": f"Bearer {os.environ['VALUEVERSE_API_KEY']}", }, timeout=20, ) res.raise_for_status() payload = res.json()