Open Alva

What is Alva

Alva is an agentic finance platform. It provides unified access to 250+ financial data sources spanning crypto, equities, ETFs, macroeconomic indicators, on-chain analytics, and social sentiment -- including spot and futures OHLCV, funding rates, company fundamentals, price targets, insider and senator trades, earnings estimates, CPI, GDP, Treasury rates, exchange flows, DeFi metrics, news feeds, social media and more!

What Open Alva Enables

The Open Alva skill connects any AI agent or IDE to the full Alva platform. With it you can:

• Access financial data -- query any of Alva's 250+ data SDKs programmatically, or bring your own data via HTTP API or direct upload.

• Run cloud-side analytics -- write JavaScript that executes on Alva Cloud in a secure runtime. No local compute, no dependencies, no infrastructure to manage.

• Build agentic playbooks -- create data pipelines, trading strategies, and scheduled automations that run continuously on Alva Cloud.

• Deploy trading strategies -- backtest with the Altra trading engine and run continuous live paper trading.

• Release and share -- turn your work into a hosted playbook web app at https://yourusername.playbook.alva.ai/playbook-name/version/index.html , and share it with the world.

In short: turn your ideas into a forever-running finance agent that gets things done for you.

Capabilities & Common Workflows

1. ALFS (Alva FileSystem)

The foundation of the platform. ALFS is a globally shared filesystem with built-in authorization. Every user has a home directory; permissions control who can read and write each path. Scripts, data feeds, playbook assets, and shared libraries all live on ALFS.

Key operations: read, write, mkdir, stat, readdir, remove, rename, copy, symlink, chmod, grant, revoke.

2. JS Runtime

Run JavaScript on Alva Cloud in a secure V8 isolate. The runtime has access to ALFS, all 250+ SDKs, HTTP networking, LLM access, and the Feed SDK. Everything executes server-side -- nothing runs on your local machine.

3. SDKHub

250+ built-in financial data SDKs. To find the right SDK for a task, use the two-step retrieval flow:

• Pick a partition from the index below.

• Call GET /api/v1/sdk/partitions/:partition/modules to see module summaries, then load the full doc for the chosen module.

SDK Partition Index

Partition Description

spot_market_price_and_volume

Spot OHLCV for crypto and equities. Price bars, volume, historical candles.

crypto_futures_data

Perpetual futures: OHLCV, funding rates, open interest, long/short ratio.

crypto_technical_metrics

Crypto technical & on-chain indicators: MA, EMA, RSI, MACD, Bollinger, MVRV, SOPR, NUPL, whale ratio, market cap, FDV, etc. (20 modules)

crypto_exchange_flow

Exchange inflow/outflow data for crypto assets.

crypto_fundamentals

Crypto market fundamentals: circulating supply, max supply, market dominance.

crypto_screener

Screen crypto assets by technical metrics over custom time ranges.

company_crypto_holdings

Public companies' crypto token holdings (e.g. MicroStrategy BTC).

equity_fundamentals

Stock fundamentals: income statements, balance sheets, cash flow, margins, PE, PB, ROE, ROA, EPS, market cap, dividend yield, enterprise value, etc. (31 modules)

equity_estimates_and_targets

Analyst price targets, consensus estimates, earnings guidance.

equity_events_calendar

Dividend calendar, stock split calendar.

equity_ownership_and_flow

Institutional holdings, insider trades, senator trading activity.

stock_screener

Screen stocks by sector, industry, country, exchange, IPO date, earnings date, financial & technical metrics. (9 modules)

stock_technical_metrics

Stock technical indicators: beta, volatility, Bollinger, EMA, MA, MACD, RSI-14, VWAP, avg daily dollar volume.

etf_fundamentals

ETF holdings breakdown.

macro_and_economics_data

CPI, GDP, unemployment, federal funds rate, Treasury rates, PPI, consumer sentiment, VIX, TIPS, nonfarm payroll, retail sales, recession probability, etc. (20 modules)

technical_indicator_calculation_helpers

50+ pure calculation helpers: RSI, MACD, Bollinger Bands, ATR, VWAP, Ichimoku, Parabolic SAR, KDJ, OBV, etc. Input your own price arrays.

feed_widgets

Social & news data feeds: news, Twitter/X, YouTube, Reddit, podcasts, web search (Brave, Grok).

ask

General news and market articles.

You can also bring your own data by uploading files to ALFS or fetching from external HTTP APIs within the runtime.

4. Altra (Alva Trading Engine)

A feed-based event-driven backtesting engine for quantitative trading strategies. A trading strategy IS a feed: all output data (targets, portfolio, orders, equity, metrics) lives under a single feed's ALFS path. Altra supports historical backtesting and continuous live paper trading, with custom indicators, portfolio simulation, and performance analytics.

5. Deploy on Alva Cloud

Once your data analytics scripts and feeds are ready, deploy them as scheduled cronjobs on Alva Cloud. They run continuously on your chosen schedule (e.g. every hour, every day). Grant public access so anyone -- or any playbook page -- can read the data.

6. Build the Playbook Web App

After your data pipelines are deployed and producing data, build the playbook's web interface. Create HTML5 pages that read from Alva's data gateway and visualize the results. Follow the Alva Design System for styling, layout, and component guidelines.

7. Release

Write the playbook HTML to ~/playbooks/{name}/index.html via fs/write , then call POST /api/v1/release/playbook to release it. Once released, the playbook is accessible at https://yourusername.playbook.alva.ai/playbook-name/version/index.html

-- ready to share with the world.

Detailed sub-documents (read these for in-depth reference):

Document Contents

api-reference.md Full REST API reference (filesystem, run, deploy, user info, time series paths)

jagent-runtime.md Writing jagent scripts: module system, built-in modules, async model, constraints

feed-sdk.md Feed SDK guide: creating data feeds, time series, upstreams, state management

altra-trading.md Altra backtesting engine: strategies, features, signals, testing, debugging

deployment.md Deploying scripts as cronjobs for scheduled execution

design-system.md Alva Design System: design tokens, colors, typography, font rules

design-widgets.md Widget design: chart cards, KPI cards, table cards, feed cards, layout grid

design-components.md Base component templates: dropdown, button, switch, modal, select, markdown

design-playbook-trading-strategy.md Trading strategy playbook guideline

adk.md Agent Development Kit: adk.agent() API, tool calling, ReAct loop, examples

Setup

All configuration is done via environment variables.

Variable Required Description

ALVA_API_KEY

yes Your API key (create and manage at alva.ai)

ALVA_ENDPOINT

no Alva API base URL. Defaults to https://api-llm.prd.alva.ai if not set

Making API Requests

All API examples in this skill use HTTP notation (METHOD /path ). Every request requires the X-Alva-Api-Key header unless marked (public, no auth).

Curl templates for reference:

Authenticated

curl -s -H "X-Alva-Api-Key: $ALVA_API_KEY" "$ALVA_ENDPOINT{path}"

Authenticated + JSON body

curl -s -H "X-Alva-Api-Key: $ALVA_API_KEY" -H "Content-Type: application/json"
"$ALVA_ENDPOINT{path}" -d '{body}'

Public read (no API key, absolute path)

curl -s "$ALVA_ENDPOINT{path}"

Discovering User Info

Retrieve your user_id and username :

GET /api/v1/me → {"id":1,"username":"alice"}

Quick API Reference

See api-reference.md for full details.

Filesystem (/api/v1/fs/ )

Method Endpoint Description

GET /api/v1/fs/read?path={path}

Read file content (raw bytes) or time series data

POST /api/v1/fs/write

Write file (raw body or JSON with data field)

GET /api/v1/fs/stat?path={path}

Get file/directory metadata

GET /api/v1/fs/readdir?path={path}

List directory entries

POST /api/v1/fs/mkdir

Create directory (recursive)

DELETE /api/v1/fs/remove?path={path}

Remove file or directory

POST /api/v1/fs/rename

Rename / move

POST /api/v1/fs/copy

Copy file

POST /api/v1/fs/symlink

Create symlink

GET /api/v1/fs/readlink?path={path}

Read symlink target

POST /api/v1/fs/chmod

Change permissions

POST /api/v1/fs/grant

Grant read/write access to a path

POST /api/v1/fs/revoke

Revoke access

Paths: ~/data/file.json (home-relative) or /alva/home/<username>/... (absolute). Public reads use absolute paths without API key.

Run (/api/v1/run )

Method Endpoint Description

POST /api/v1/run

Execute JavaScript (inline code or entry_path to a script on filesystem)

Deploy (/api/v1/deploy/ )

Method Endpoint Description

POST /api/v1/deploy/cronjob

Create a cronjob

GET /api/v1/deploy/cronjobs

List cronjobs (paginated)

GET /api/v1/deploy/cronjob/:id

Get cronjob details

PATCH /api/v1/deploy/cronjob/:id

Update cronjob (name, cron, args)

DELETE /api/v1/deploy/cronjob/:id

Delete cronjob

POST /api/v1/deploy/cronjob/:id/pause

Pause cronjob

POST /api/v1/deploy/cronjob/:id/resume

Resume cronjob

Release (/api/v1/release/ )

Method Endpoint Description

POST /api/v1/release/feed

Register feed (DB + link to cronjob task). Call after deploying cronjob.

POST /api/v1/release/playbook

Release playbook for public hosting. Call after writing playbook HTML.

Name uniqueness: Both name in releaseFeed and releasePlaybook must be unique within your user space. Use GET /api/v1/fs/readdir?path=/feeds or GET /api/v1/fs/readdir?path=/playbooks to check existing names before releasing.

SDK Documentation (/api/v1/sdk/ )

Method Endpoint Description

GET /api/v1/sdk/doc?name={module_name}

Get full doc for a specific SDK module

GET /api/v1/sdk/partitions

List all SDK partitions

GET /api/v1/sdk/partitions/:partition/summary

Get one-line summaries of all modules in a partition

SDK retrieval flow: pick a partition from the index above → call /partitions/:partition/summary to see module summaries → call /sdk/doc?name=... to load the full doc for the chosen module.

Trading Pair Search (/api/v1/trading-pairs/ )

Method Endpoint Description

GET /api/v1/trading-pairs/search?q={q}

Search trading pairs by base asset (fuzzy match)

Search before writing code to check which symbols/exchanges Alva supports. Supports exact match + prefix fuzzy search by base asset or alias. Comma-separated queries for multiple searches.

GET /api/v1/trading-pairs/search?q=BTC,ETH → {"trading_pairs":[{"base":"BTC","quote":"USDT","symbol":"BINANCE_PERP_BTC_USDT","exchange":"binance","type":"crypto-perp","fee_rate":0.001,...},...]}

User Info

Method Endpoint Description

GET /api/v1/me

Get authenticated user's id and username

Runtime Modules Quick Reference

Scripts executed via /api/v1/run run in a V8 isolate. See jagent-runtime.md for full details.

Module require() Description

alfs require("alfs")

Filesystem (uses absolute paths /alva/home/<username>/... )

env require("env")

userId , username , args from request

net/http require("net/http")

fetch(url, init) for async HTTP requests

@alva/algorithm require("@alva/algorithm")

Technical indicators and statistics

@alva/feed require("@alva/feed")

Feed SDK for persistent data pipelines + FeedAltra trading engine

@alva/adk require("@alva/adk")

Agent SDK for LLM requests — agent() for LLM agents with tool calling

@test/suite require("@test/suite")

Jest-style test framework (describe , it , expect , runTests )

SDKHub: 250+ data modules available via require("@arrays/crypto/ohlcv:v1.0.0") etc. Version suffix is optional (defaults to v1.0.0 ). To discover function signatures and response shapes, use the SDK doc API (GET /api/v1/sdk/doc?name=... ).

Key constraints: No top-level await (wrap script in (async () => { ... })(); ). No Node.js builtins (fs , path , http ). Module exports are frozen.

Feed SDK Quick Reference

See feed-sdk.md for full details.

Feeds are persistent data pipelines that store time series data, readable via filesystem paths.

const { Feed, feedPath, makeDoc, num } = require("@alva/feed"); const { getCryptoKline } = require("@arrays/crypto/ohlcv:v1.0.0"); const { indicators } = require("@alva/algorithm");

const feed = new Feed({ path: feedPath("btc-ema") });

feed.def("metrics", { prices: makeDoc("BTC Prices", "Close + EMA10", [num("close"), num("ema10")]), });

(async () => { await feed.run(async (ctx) => { const raw = await ctx.kv.load("lastDate"); const lastDateMs = raw ? Number(raw) : 0;

const now = Math.floor(Date.now() / 1000);
const start =
  lastDateMs > 0 ? Math.floor(lastDateMs / 1000) : now - 30 * 86400;

const bars = getCryptoKline({
  symbol: "BTCUSDT",
  start_time: start,
  end_time: now,
  interval: "1h",
})
  .response.data.slice()
  .reverse();
const closes = bars.map((b) => b.close);
const ema10 = indicators.ema(closes, { period: 10 });

const records = bars
  .map((b, i) => ({
    date: b.date,
    close: b.close,
    ema10: ema10[i] || null,
  }))
  .filter((r) => r.date > lastDateMs);

if (records.length > 0) {
  await ctx.self.ts("metrics", "prices").append(records);
  await ctx.kv.put("lastDate", String(records[records.length - 1].date));
}

}); })();

Feed output is readable at: ~/feeds/btc-ema/v1/data/metrics/prices/@last/100

Data Modeling Patterns

All data produced by a feed should use feed.def()

• ctx.self.ts().append() . Do not use alfs.writeFile() for feed output data.

Pattern A -- Snapshot (latest-wins): For data that represents current state (company detail, ratings, price target consensus). Use start-of-day as the date so re-runs overwrite.

const today = new Date(); today.setHours(0, 0, 0, 0); await ctx.self .ts("info", "company") .append([ { date: today.getTime(), name: company.name, sector: company.sector }, ]);

Read @last/1 for current snapshot, @last/30 for 30-day history.

Pattern B -- Event log: For timestamped events (insider trades, news, senator trades). Each event uses its natural date. Same-date records are auto-grouped.

const records = trades.map((t) => ({ date: new Date(t.transactionDate).getTime(), name: t.name, type: t.type, shares: t.shares, })); await ctx.self.ts("activity", "insiderTrades").append(records);

Pattern C -- Tabular (versioned batch): For data where the whole set refreshes each run (top holders, EPS estimates). Stamp all records with the same run timestamp; same-date grouping stores them as a batch.

const now = Date.now(); const records = holdings.map((h, i) => ({ date: now, rank: i + 1, name: h.name, marketValue: h.value, })); await ctx.self.ts("research", "institutions").append(records);

Data Type Pattern Date Strategy Read Query

OHLCV, indicators Time series (standard) Bar timestamp @last/252

Company detail, ratings Snapshot (A) Start of day @last/1

Insider trades, news Event log (B) Event timestamp @last/50

Holdings, estimates Tabular (C) Run timestamp @last/N

See feed-sdk.md for detailed data modeling examples and deduplication behavior.

Deploying Feeds

Every feed follows a 6-step lifecycle:

• Write -- define schema + incremental logic with ctx.kv

• Upload -- write script to ~/feeds/<name>/v1/src/index.js

• Test -- POST /api/v1/run with entry_path to verify output

• Grant -- make feed public via POST /api/v1/fs/grant

• Deploy -- POST /api/v1/deploy/cronjob for scheduled execution

• Release -- POST /api/v1/release/feed to register the feed in the database (requires the task_id from the deploy step)

Data Type Recommended Schedule Rationale

Stock OHLCV + technicals 0 */4 * * * (every 4h) Markets update during trading hours

Company detail, price targets 0 8 * * * (daily 8am) Changes infrequently

Insider/senator trades 0 8 * * * (daily 8am) SEC filings are daily

Earnings estimates 0 8 * * * (daily 8am) Updated periodically

See deployment.md for the full deployment guide and API reference.

Debugging Feeds

Resetting Feed Data (development only)

During development, use the REST API to clear stale or incorrect data. Do not use this in production.

Clear a specific time series output

DELETE /api/v1/fs/remove?path=~/feeds/my-feed/v1/data/market/ohlcv&recursive=true

Clear an entire group (all outputs under "market")

DELETE /api/v1/fs/remove?path=~/feeds/my-feed/v1/data/market&recursive=true

Full reset: clear ALL data + KV state (removes the data mount, re-created on next run)

DELETE /api/v1/fs/remove?path=~/feeds/my-feed/v1/data&recursive=true

Inline Debug Snippets

Test SDK shapes before building a full feed:

POST /api/v1/run {"code":"const { getCryptoKline } = require("@arrays/crypto/ohlcv:v1.0.0"); JSON.stringify(Object.keys(getCryptoKline({ symbol: "BTCUSDT", start_time: 0, end_time: 0, interval: "1h" })));"}

Altra Trading Engine Quick Reference

See altra-trading.md for full details.

Altra is a feed-based event-driven backtesting engine. A trading strategy IS a feed: all output data lives under a single ALFS path. Decisions execute at bar CLOSE.

const { createOHLCVProvider } = require("@arrays/data/ohlcv-provider:v1.0.0"); const { FeedAltraModule } = require("@alva/feed"); const { FeedAltra, e, Amount } = FeedAltraModule;

const altra = new FeedAltra( { path: "~/feeds/my-strategy/v1", startDate: Date.parse("2025-01-01T00:00:00Z"), portfolioOptions: { initialCash: 1_000_000 }, simOptions: { simTick: "1min", feeRate: 0.001 }, perfOptions: { timezone: "UTC", marketType: "crypto" }, }, createOHLCVProvider(), );

const dg = altra.getDataGraph(); dg.registerOhlcv("BINANCE_SPOT_BTC_USDT", "1d"); dg.registerFeature({ name: "rsi" /* ... */ });

altra.setStrategy(strategyFn, { trigger: { type: "events", expr: e.ohlcv("BINANCE_SPOT_BTC_USDT", "1d") }, inputConfig: { ohlcvs: [{ id: { pair: "BINANCE_SPOT_BTC_USDT", interval: "1d" } }], features: [{ id: "rsi" }], }, initialState: {}, });

(async () => { await altra.run(Date.now()); })();

Deployment Quick Reference

See deployment.md for full details.

Deploy feed scripts or tasks as cronjobs for scheduled execution:

POST /api/v1/deploy/cronjob {"path":"~/feeds/btc-ema/v1/src/index.js","cron_expression":"0 */4 * * *","name":"BTC EMA Update"}

Cronjobs execute the script via the same jagent runtime as /api/v1/run . Max 20 cronjobs per user. Min interval: 1 minute.

After deploying a cronjob, register the feed and release the playbook for public hosting. The playbook HTML must already be written to ALFS at ~/playbooks/{name}/index.html via fs/write before releasing.

Important: Feed names and playbook names must be unique within your user space. Before creating a new feed or playbook, use GET /api/v1/fs/readdir?path=/feeds or GET /api/v1/fs/readdir?path=/playbooks

to check for existing names and avoid conflicts.

1. Release feed (register in DB, link to cronjob)

Call this AFTER deploying the cronjob via POST /api/v1/deploy/cronjob

POST /api/v1/release/feed {"name":"btc-ema","version":"1.0.0","task_id":42} → {"feed_id":100,"name":"btc-ema","feed_major":1}

2. Release playbook (makes it accessible at https://username.playbook.alva.ai/playbook-name/version/index.html)

Call this AFTER writing the playbook HTML to ~/playbooks/{name}/index.html

POST /api/v1/release/playbook {"name":"btc-dashboard","version":"v1.0.0","feeds":[{"feed_id":100}]} → {"playbook_id":99,"version":"v1.0.0"}

The playbook will be accessible at https://alice.playbook.alva.ai/btc-dashboard/v1.0.0/index.html .

Alva Design System

All Alva playbook pages, dashboards, and widgets must follow the Alva Design System. The system defines design tokens (colors, spacing, shadows), typography rules, and component/widget templates.

Key rules:

• Font: Delight (Regular 400, Medium 500). No Semibold/Bold. Font files: Delight-Regular.ttf, Delight-Medium.ttf

• Page background: --b0-page (#ffffff )

• Semantic colors: --main-m3 (bullish/green), --main-m4 (bearish/red), --main-m1 (Alva theme/teal)

• Charts: Use ECharts. Select colors from the chart palette in design-system.md. Grey only when >= 3 series.

• Widgets: No borders on widget cards. Chart cards use dotted background; table card has no background; other cards use --grey-g01 .

• Grid: 8-column grid (web), 4-column grid (mobile). Column spans must sum to 8 per row.

Reference documents (read for detailed specs when building playbook web apps):

When Read

Design tokens, typography, font rules, general guidelines design-system.md

Widget types, chart/KPI/table/feed cards, grid layout design-widgets.md

Component templates (button, dropdown, modal, select, switch, markdown) design-components.md

Trading strategy playbook layout, sections, and content guidelines design-playbook-trading-strategy.md

Filesystem Layout Convention

Path Purpose

~/tasks/<name>/src/

Task source code

~/feeds/<name>/v1/src/

Feed script source code

~/feeds/<name>/v1/data/

Feed synth mount (auto-created by Feed SDK)

~/playbooks/<name>/

Playbook web app assets

~/data/

General data storage

~/library/

Shared code modules

Prefer using the Feed SDK for all data organization, including point-in-time snapshots. Store snapshots as single-record time series rather than raw JSON files via alfs.writeFile() . This keeps all data queryable through a single consistent read pattern (@last , @range , etc.).

Common Pitfalls

• @last returns chronological (oldest-first) order, consistent with @first and @range . No manual sorting needed.

• Time series reads return flat JSON records. Paths with @last , @range , etc. return JSON arrays of flat records like [{"date":...,"close":...,"ema10":...}] . Regular paths return file content with Content-Type: application/octet-stream .

• last(N) limits unique timestamps, not records. When multiple records share a timestamp (grouped via append() ), auto-flatten may return more than N individual records.

• The data/ in feed paths is the synth mount. feedPath("my-feed") gives ~/feeds/my-feed/v1 , and the Feed SDK mounts storage at <feedPath>/data/ . Don't name your group "data" or you'll get data/data/... .

• Public reads require absolute paths. Unauthenticated reads must use /alva/home/<username>/... (not ~/... ). Discover your username via GET /api/v1/me .

• Top-level await is not supported. Wrap async code in (async () => { ... })(); .

• require("alfs") uses absolute paths. Inside the V8 runtime, alfs.readFile() needs full paths like /alva/home/alice/... . Get your username from require("env").username .

• No Node.js builtins. require("fs") , require("path") , require("http")

do not exist. Use require("alfs") for files, require("net/http") for HTTP.

• Altra run() is async. FeedAltra.run() returns a Promise<RunResult> . Always await it: const result = await altra.run(endDate);

• Altra decisions happen at bar CLOSE. Feature timestamps must use bar.endTime , not bar.date . Using bar.date introduces look-ahead bias.

• Altra lookback: feature vs strategy. Feature lookback controls how many bars the feature computation sees. Strategy lookback controls how many feature outputs the strategy function sees. They are independent.

• Cronjob path must point to an existing script. The deploy API validates the entry_path exists via filesystem stat before creating the cronjob.

Resource Limits

Resource Limit

Write payload 10 MB max per request

HTTP response body 128 MB max

Max cronjobs per user 20

Min cron interval 1 minute

Error Responses

All errors return: {"error":{"code":"...","message":"..."}}

HTTP Status Code Meaning

400 INVALID_ARGUMENT Bad request or invalid path

401 UNAUTHENTICATED Missing or invalid API key

403 PERMISSION_DENIED Access denied

404 NOT_FOUND File/directory not found

429 RATE_LIMITED Rate limit / runner pool exhausted

500 INTERNAL Server error